Look, you've probably been using gem install for everything so far. That's fine for a quick experiment, but in a professional environment, that's a recipe for disaster. Imagine you send your code to a teammate, and it crashes because they have version 3.1 of a gem while you're using 2.8. You'll spend your entire afternoon debugging environment issues instead of writing code. That's why we use Bundler.

To show you how this works, let's build a small "Joke of the Day" CLI tool that fetches a joke from an API and prints it to the terminal in a vibrant color. It's simple, but it requires a few external dependencies.

Setting up our project manifest

First, I'll create a new directory for this project. Instead of just installing gems globally, I'm going to create a Gemfile. Think of this as the "shopping list" for your project. It tells Ruby exactly which libraries are required to make the code run.

mkdir joke_cli
cd joke_cli
bundle init

Running bundle init creates a boilerplate Gemfile. If you open it, you'll see a source line pointing to rubygems.org. That's just telling Bundler where to download the gems from. I'll leave that alone and start adding the tools I actually need.

Adding the horsepower

For this tool, I want httpx for making the API request (it's faster and more modern than the standard library) and colorize because plain white text in a terminal is boring.

I'll edit my Gemfile to look like this:

source 'https://rubygems.org'

gem 'httpx'
gem 'colorize'

Now, I'll run bundle install. This is where the magic happens. Bundler doesn't just install the gems; it calculates the dependencies of those gems to make sure there are no version conflicts. If httpx required a specific version of another gem that colorize hated, Bundler would scream at me now rather than letting the app crash at runtime.

Hitting the 'LoadError' wall

Now I'll write the actual script. I'll call it joke.rb.

require 'httpx'
require 'colorize'

response = HTTPX.get("https://official-joke-api.appspot.com/random_joke")
data = JSON.parse(response.body.to_s)

puts "Setup: #{data['setup']}".blue
puts "Punchline: #{data['punchline']}".green

I'm going to try and run this with ruby joke.rb. But wait—I get a LoadError: cannot load such file -- httpx. I'm confused; I just ran bundle install!

Here is where I messed up: I forgot that bundle install installs gems into a specific environment, but running ruby directly looks at my global system gems. Since I haven't installed these globally (and I shouldn't), Ruby can't find them. To fix this, I need to tell Ruby to run the script within the context of my bundle.

The fix is simple: use bundle exec.

bundle exec ruby joke.rb

Now it works perfectly. bundle exec ensures that the Ruby interpreter uses exactly the versions specified in our project's lockfile.

The magic of the lockfile

You'll notice a new file in your folder: Gemfile.lock. Do not delete this, and do not ignore it in your .gitignore. While the Gemfile says "I want the colorize gem," the Gemfile.lock says "I am using colorize version 1.1.0."

This is the "snapshot" of your environment. When your teammate clones your repo and runs bundle install, Bundler looks at the lockfile first. They get version 1.1.0, exactly what you have, even if version 1.2.0 was released five minutes ago. This is how we avoid the dreaded "it works on my machine" syndrome.

📋 Practical Task

Build a Bundled Currency Converter

Create a new Ruby project that converts USD to EUR using a hard-coded exchange rate, but uses external gems to handle the logic and display. Your project must meet these requirements:

• Initialize a Gemfile using Bundler.
• Include the money gem (for currency handling) and the rainbow gem (for colored terminal output).
• Run bundle install to generate a Gemfile.lock.
• Create a script converter.rb that:
  • Requires the necessary gems.
  • Uses the Money class to define an amount in USD.
  • Calculates the EUR equivalent (you can use a simple multiplication for the rate).
  • Prints the result to the terminal using a color from the rainbow gem.
• Ensure the script is executed using bundle exec to verify your environment is locked correctly.