Reading a lot of code from very senior engineers is probably one of the best ways to level up as a Ruby on Rails developer. By doing so, we can learn new tips and techniques that we can reuse in our jobs. Thanks to open source, we can read code written by the best developers from all over the world, and for free!

However, reading code from a Ruby gem or a Rails engine for the first time without being guided can be daunting. There are so many files; how do we even know where to start?

In this three-part series, we are going to read the source code from the Showcase Rails engine.

We will learn about:

• The main files in a Rails engine
• How to read source code without getting lost

In this first part, we'll set up Showcase in a Rails application and run it locally.

Let’s get started!

What is Showcase for Ruby on Rails?

Showcase (written mainly by Kasper Timm Hansen, Rails consultant and former Rails Core team member) is a Rails engine that allows us to document a design system. Here is what it looks like:

For a good understanding of how Showcase works before reading its code, we should use it in a project. Let's create a new Rails application and cd into it:

rails new showcase-test
cd showcase-test

According to the Showcase README, we need to add showcase-rails and rouge to our Gemfile:

# Gemfile
 
group :development, :test do
  gem "showcase-rails"
  gem "rouge", require: false
end

If you are not familiar with the rouge gem, it is a syntax highlighter used to highlight code in the "View source" accordion, as shown below:

As we add new gems to our Gemfile, let's not forget to run bundle install. We then have to mount the engine in our routes to make the engine's routes available to our main Rails application:

# config/routes.rb
 
Rails.application.routes.draw do
  mount Showcase::Engine, at: "/docs/showcase" if defined?(Showcase::Engine)
  # ...
end

Build a Component

Let’s now create our first component. Every application needs buttons, right? Let’s create one with three different sizes:

<%# app/views/components/_button.html.erb %>
 
<% classes = { small: "btn--sm", medium: "btn--md", large: "btn--lg" }.fetch(mode) %>
<%= tag.button content, class: [ "btn", classes ] %>

To style our button, we will need CSS, of course. As this is just a demo application, we'll simply write our CSS in the application.css file generated for us:

/* app/assets/stylesheets/application.css */
 
.btn {
  font-size: var(--btn-font-size);
  padding: 0.5em 1em;
  border-radius: 0.5em;
  color: white;
  background-color: black;
}
 
.btn--sm {
  --btn-font-size: 0.75rem;
}
 
.btn--md {
  --btn-font-size: 1rem;
}
 
.btn--lg {
  --btn-font-size: 1.25rem;
}

Finally, let’s create the preview file to document our button component:

<%# app/views/showcase/previews/components/_button.html.erb %>
 
<% showcase.badge :partial, :component %>
<% showcase.description "Button is our standard element for what to click on" %>
 
<% showcase.sample "Small" do %>
  <%= render "components/button", content: "Button content", mode: :small %>
<% end %>
 
<% showcase.sample "Large", description: "This is our larger button" do %>
  <%= render "components/button", content: "Button content", mode: :large %>
<% end %>
 
<% showcase.options do |o| %>
  <% o.required :content, "The content to output as the button text" %>
  <% o.optional :mode, "We support three modes", options: %i[ small medium large ] %>
<% end %>

We can now navigate to http://localhost:3000/docs/showcase/previews/components/button to see our first preview:

Gems and engines allow us to use other people's code in our Rails applications. If we use those gems and have absolutely no idea how they work, we have an opportunity to learn something new.

Setting Up Our Ruby on Rails Development Environment

Let's learn about the magic behind gems by reading some source code!

Rails Engines File Structure

The first step to read or contribute to a Rails engine is to clone the repository locally:

git clone git@github.com:bullet-train-co/showcase.git
cd showcase

Let’s open the repository with our text editor and have a look at the different files:

.
├── Gemfile
├── showcase.gemspec
├── app
│   ├── assets
│   ├── controllers
│   ├── helpers
│   ├── jobs
│   ├── mailers
│   ├── models
│   └── views
├── config
│   └── routes.rb
├── lib
│   ├── showcase
│   ├── showcase-rails.rb
│   └── showcase.rb
└── test
    ├── controllers
    ├── dummy
    ├── fixtures
    ├── helpers
    ├── integration
    ├── mailers
    ├── models
    └── views

The first thing we should realize is that the file structure is very similar to a standard Rails application with models, views, controllers, and routes. In fact, we can view a Rails engine as a standalone Rails application that will get merged into our main Rails application!

Our engine also has a /test folder used to test the engine, with a special /dummy folder that is particularly useful. If we have a look at the file structure of the /test/dummy folder, we can see the following tree:

.
├── Rakefile
├── app
│   ├── assets
│   ├── channels
│   ├── controllers
│   ├── helpers
│   ├── jobs
│   ├── mailers
│   ├── models
│   └── views
├── bin
│   ├── rails
│   ├── rake
│   └── setup
├── config
│   ├── application.rb
│   ├── boot.rb
│   ├── cable.yml
│   ├── database.yml
│   ├── environment.rb
│   ├── environments
│   ├── initializers
│   ├── locales
│   ├── puma.rb
│   ├── routes.rb
│   └── storage.yml
├── config.ru
├── lib
│   └── assets
├── log
└── public
    ├── 404.html
    ├── 422.html
    ├── 500.html
    └── favicon.ico

Wait a minute, isn't this the exact file structure of a standard Rails application? Yes, it is! The test/dummy folder contains a real Rails application that we can launch in the browser for development. It is also useful to write tests for our engine in the context of a real Rails application.

Running the Rails Engine Locally

Now that we have a better understanding of the file structure, it's useful to be able to run this test/dummy Rails application on localhost.

As with any other Rails application, the first step is to install dependencies. Before we do so, we have to talk about the showcase.gemspec and the Gemfile. If we open the showcase.gemspec, it currently contains the following code:

# showcase.gemspec
 
require_relative "lib/showcase/version"
 
Gem::Specification.new do |spec|
  spec.name        = "showcase-rails"
  spec.version     = Showcase::VERSION
  spec.authors     = ["Daniel Pence", "Kasper Timm Hansen"]
  spec.email       = ["hey@kaspth.com"]
  spec.homepage    = "https://github.com/kaspth/showcase"
  spec.summary     = "Showcase helps you show off and document your partials, components, view helpers and Stimulus controllers."
  spec.license     = "MIT"
 
  spec.metadata["homepage_uri"]    = spec.homepage
  spec.metadata["source_code_uri"] = spec.homepage
  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
  spec.files = Dir.chdir(File.expand_path(__dir__)) do
    Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md"]
  end
 
  spec.add_dependency "rails", ">= 6.1.0"
  spec.add_development_dependency "tailwindcss-rails"
end

Most of it is just information about the authors, the license, and useful links that you'll find on the RubyGems website. However, the most interesting part is the last two lines:

# showcase.gemspec
 
spec.add_dependency "rails", ">= 6.1.0"
spec.add_development_dependency "tailwindcss-rails"

The first line indicates that showcase depends on Rails version 6.1 or above.

The second line indicates a development dependency on tailwindcss-rails. This means that showcase uses tailwindcss-rails for styling purposes in development, but you do not need to have tailwindcss-rails installed in your main Rails application to use showcase.

Let’s now have a look at the Gemfile:

# Gemfile
 
source "https://rubygems.org"
git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
# Specify your gem's dependencies in showcase.gemspec.
gemspec
 
gem "sqlite3"
 
rails_version = ENV.fetch("RAILS_VERSION", "7.0")
 
rails_constraint = if rails_version == "main"
  {github: "rails/rails"}
else
  "~> #{rails_version}.0"
end
 
gem "rails", rails_constraint
gem "sprockets-rails"
 
# Start debugger with binding.b [https://github.com/ruby/debug]
# gem "debug", ">= 1.0.0"
 
gem "puma"
gem "rouge", require: false
 
group :test do
  # Code omitted for brevity
end

The Gemfile should look familiar: It lists additional development dependencies used to run the /test/dummy application.

Those dependencies are from the gemspec, plus the additional ones listed in our Gemfile. This Gemfile also enables us to choose the Rails version we want to use in development by passing the RAILS_VERSION environment variable, and defaults to version 7.0.

Note: While writing this article, I realized there is a small bug when running Showcase with Rails 7.0.X. It is not a very interesting bug to talk about, so we'll just ignore it and use Rails 8.X version instead.

As specified in the Gemfile, we can use the RAILS_VERSION environment variable to specify the Rails version we want to use. To do this, we simply have to prefix all of our commands with RAILS_VERSION=8:

RAILS_VERSION=8 bundle install
RAILS_VERSION=8 bin/rails server
RAILS_VERSION=8 bin/rails console

Let's try to install the dependencies now:

RAILS_VERSION=8 bundle install

With all the dependencies installed, we should now be able to run the Rails server:

RAILS_VERSION=8 bin/rails server

If we now visit http://localhost:3000, we should see the showcase landing page from the test/dummy application:

We should also be able to see our Rails server logs in the terminal:

Started GET "/docs/showcase" for ::1 at 2025-07-24 11:57:42 +0200
Processing by Showcase::EngineController#index as HTML
...

This is going to be very helpful when analyzing how Showcase works, as we'll simply be able to follow the logs!

Next Up: The Button Component Preview

In this post, we learned:

• How to use showcase in a real Rails application
• What the different files in a Rails engine are used for
• How to run the test/dummy Rails application locally

In the next part of this series, we will read some Ruby code written by experienced Rails developers. In order to do this without getting lost, we are going to choose one feature of the showcase engine — the button component preview — and analyze how it works.

Until then, happy coding!