Component-Based Rails Applications


This book is no longer available for sale.

Component-Based Rails Applications

Large Domains Under Control

About the Book

As Rails applications grow and mature the help we get from the framework shrinks - to some, it even feels like the framework gets in the way. It doesn't need to be that way! With component-based applications we have a great way to control the complexity of our domain. In areas where Rails alone does not lend much support, we look to proven patterns to create a meaningful support structure for all of our applications.

With this book you will learn

  • How to create components with gems and engines.
  • How to spot and fix common technical issues
  • What refactorings to use to tease out new components 
  • How to extract your first component from any existing project 
  • How to apply component-based design together with the hexagonal and DCI architectural patterns

You will hear from others that have taken the journey and how they used components to improve their projects.

As you will learn through this book, components are also a great stepping stones towards micro-service architectures.

The intent of this book goes well beyond Rails: We want you to become a better software engineer. Components are a proven method of software development and all popular programming languages allow the creating of components in some way. The learnings from this book will improve your ability to create maintainable applications in any language!

About the Authors

Stephan Hagemann
Stephan Hagemann

Stephan leads the product infrastructure engineering team at Gusto. Gusto has quite a bit of Ruby on Rails in the software behind their offerings and provides the perfect ground for the analysis of complex applications due to "Payroll" being both a deep and very wide domain. And Gusto is a lot more than payroll.

Stephan is the author of Component-based Rails Applications in which he lays out the previous iteration of Ruby and Rails modularization based on gems and engines. He is currently working on a new book called Gradual Modularization for Ruby and Rails, which improves on his previous ideas by reducing the cost of the needed work and increasing the opportunities for benefiting from it.

Find out more about Stephan at

Ryan Platte
Ryan Platte

Ryan is an independent software developer. His experience includes work for top national brands, startups, and non-profits. He lives in Rochester, NY with his family.

Benjamin Smith
Benjamin Smith

Benjamin Smith is the CTO at hobbyDB. He has a strong passion for TDD, pairing, Agile and using technologies that get out of the programmer's way. When not writing code, he follows his other passions into the outdoors to rock climb, back country snowboard, and river surf.

Enrico Teotti
Enrico Teotti

Enrico has been working in the IT industry since 2001, first developing in C# .NET, after that attracted to open source and Linux terminal servers then from 2005 Ruby and Rails. Passionate about agile methodologies, TDD and building maintainable software that delivers business value. Blogging at

Table of Contents

  • Preface
  • 1. Introduction
    • 1.1 Component-Based Rails
      • 1.1.1 What Is It?
      • 1.1.2 History Repeating?
    • 1.2 Component-Based Ruby
    • 1.3 The Application Continuum
    • 1.4 What This Book Does not Cover
      • 1.4.1 Ruby and Rails Basics
      • 1.4.2 Rails 2
    • 1.5 Related Works
    • 1.6 Structure of This Book
  • 2. Introducing the First Component
    • 2.1 How Do I Start Writing a CBRA App?
    • 2.2 Plain vs --full vs --mountable Engines - Which Command Line Options Should I Use for Engine Creation?
      • 2.2.1 Plain Plugin
      • 2.2.2 Full Engine
      • 2.2.3 Mountable Engine
    • 2.3 How do Engine Routes and Engine Mounting Work?
    • 2.4 How Do I Handle Migrations Inside of a Component?
      • 2.4.1 Installing Engine Migrations With Rake
      • 2.4.2 Loading Engine Migrations in Place
      • 2.4.3 Known Issues
    • 2.5 How Do I Handle Dependencies in My CBRA App?
      • 2.5.1 Adding a Different Templating Library: slim (Adding a Regular Gem)
      • 2.5.2 Locking Down Gem Versions
      • 2.5.3 Adding the Rating Calculation Library: trueskill (Adding the Development Version of a Gem)
      • 2.5.4 Adding a Different Testing Framework: rspec-rails (Adding Development Dependencies)
    • 2.6 How Do I Test My Component?
      • 2.6.1 ActiveRecord Model Specs
      • 2.6.2 Non-ActiveRecord Model Specs
      • 2.6.3 Controller Specs
      • 2.6.4 Helper Spec
      • 2.6.5 View Specs
      • 2.6.6 Routing Specs
      • 2.6.7 Feature Specs
    • 2.7 How Do I Test the Main Application?
      • 2.7.1 What to Test in the Main App
      • 2.7.2 How to Put Everything Together
      • 2.7.3 How to Set Up a Continuous Integration (CI) Server
    • 2.8 How Do I Load Component Assets Properly?
      • 2.8.1 Production-Ready Assets
    • 2.9 How to set up databases with engines?
    • 2.10 How Do I Deploy to Production?
      • 2.10.1 Deploying to Heroku
      • 2.10.2 Deploying to Pivotal Web Services
    • 2.11 How Do I Update My Application’s Dependencies?
      • 2.11.1 Updating the Bundle in All Components
      • 2.11.2 Updating Every Component’s Gem Version
      • 2.11.3 Updating Rails
      • 2.11.4 Long Running Dependency Updates
      • 2.11.5 Listing a Dependency Only Once
    • 2.12 How Do I Make it More Clear That This App is Different?
      • 2.12.1 Why Would I Want to Change That?
      • 2.12.2 How CBRA Can Change How I Present and Perceive My App
      • 2.12.3 Making CI and PaaS Work With the New Structure
      • 2.12.4 What is Next?
  • 3. From One Component to Many Components
    • 3.1 Why Would I Ever Add Another Component?
      • 3.1.1 Improved Communication
      • 3.1.2 Improved Collaboration
      • 3.1.3 Improved Creation
      • 3.1.4 Improved Maintenance
      • 3.1.5 Improved Comprehension
    • 3.2 Determining What to Extract - Bottum-up
    • 3.3 Refactoring: Extract Domain Gem - Predictor
      • 3.3.1 Fixing Inside-out - Making AppComponent Work Again
      • 3.3.2 Last Step: Ensure That the App Works
      • 3.3.3 Summary of Bottom-Up Component Extractions
    • 3.4 Determining What to Extract - Top-down
      • 3.4.1 Unclear dependency direction
      • 3.4.2 Not everything needs the predictor
      • 3.4.3 Implications of the first set of extractions
      • 3.4.4 Problem with the current solution
      • 3.4.5 Reducing needed dependencies
    • 3.5 Refactoring: Pulling Up a UI Component - TeamAdmin, GameAdmin, PredictionUI, WelcomeUI
      • 3.5.1 Generate
      • 3.5.2 Move
      • 3.5.3 Fix, part 1: Reusing test helpers
      • 3.5.4 Fix, part 2: Routing issues
      • 3.5.5 Fix, part 3: The container application
    • 3.6 Refactoring: Pushing Down a Model Component - Teams, Games
      • 3.6.1 Getting Away With Less
      • 3.6.2 Fixing Teams’ tests
      • 3.6.3 Fixing Everything Else
    • 3.7 Refactoring: Improve Naming of Component - AppComponent to WebUI
      • 3.7.1 Whatever Happened to AppComponent?
      • 3.7.2 Refactoring Component Names
      • 3.7.3 Refactoring a Component Name Throughout the Application
      • 3.7.4 An Even More Mechanical Approach
    • 3.8 More Component Refactoring Patterns
      • 3.8.1 Splitting One Component in Two: Disentangling Unrelated Concepts
      • 3.8.2 API Component
      • 3.8.3 3rd Party Service Adapter
      • 3.8.4 Common functionality component
  • 4. From Ball Of Mud to First Components
    • 4.1 Small Steps
    • 4.2 One Big Step
      • 4.2.1 Prerequisites
      • 4.2.2 Script This!
      • 4.2.3 A Scripted Refactoring
      • 4.2.4 Cleaning Up persistence
      • 4.2.5 Using persistence
      • 4.2.6 Summary
  • 5. Component-based Rails in relation to other patterns
    • 5.1 Hexagonal Architecture
      • 5.1.1 Hexagonal Architecture and CBRA
      • 5.1.2 Implementing Hexagonal Rails with CBRA
      • 5.1.3 Teasing out an adapter in the frontend
      • 5.1.4 A repository for data storage
      • 5.1.5 Swappable data storage
      • 5.1.6 Summary
    • 5.2 Data-Context-Integration (DCI)
      • 5.2.1 DCI and CBRA
      • 5.2.2 Implementing DCI with CBRA
      • 5.2.3 Summary
  • 6. Case Studies
    • 6.1 Using components for good object-oriented design — Ryan Platte
      • 6.1.1 About me
      • 6.1.2 Without packages, you have a mess
      • 6.1.3 A clean way to juggle integrations
      • 6.1.4 Approaching the transition gradually
      • 6.1.5 Depending only on the domain
      • 6.1.6 Shell commands
      • 6.1.7 Moving into a new business
      • 6.1.8 Our experiences
    • 6.2 Stories of Engines — Benjamin Lee Smith
      • 6.2.1 Intro
      • 6.2.2 Engines Project #1: The from-scratch-rebuild
    • 6.3 Using components to deploy parts of a Rails applications — Enrico Teotti
      • 6.3.1 About me
      • 6.3.2 A straightforward evolving application
      • 6.3.3 Let’s join the SOA wagon!
      • 6.3.4 Let’s share Engines on a private gemserver!
      • 6.3.5 Component based with local gems and Engines
  • Notes

The Leanpub 60 Day 100% Happiness Guarantee

Within 60 days of purchase you can get a 100% refund on any Leanpub purchase, in two clicks.

Now, this is technically risky for us, since you'll have the book or course files either way. But we're so confident in our products and services, and in our authors and readers, that we're happy to offer a full money back guarantee for everything we sell.

You can only find out how good something is by trying it, and because of our 100% money back guarantee there's literally no risk to do so!

So, there's no reason not to click the Add to Cart button, is there?

See full terms...

80% Royalties. Earn $16 on a $20 book.

We pay 80% royalties. That's not a typo: you earn $16 on a $20 sale. If we sell 5000 non-refunded copies of your book or course for $20, you'll earn $80,000.

(Yes, some authors have already earned much more than that on Leanpub.)

In fact, authors have earnedover $13 millionwriting, publishing and selling on Leanpub.

Learn more about writing on Leanpub

Free Updates. DRM Free.

If you buy a Leanpub book, you get free updates for as long as the author updates the book! Many authors use Leanpub to publish their books in-progress, while they are writing them. All readers get free updates, regardless of when they bought the book or how much they paid (including free).

Most Leanpub books are available in PDF (for computers) and EPUB (for phones, tablets and Kindle). The formats that a book includes are shown at the top right corner of this page.

Finally, Leanpub books don't have any DRM copy-protection nonsense, so you can easily read them on any supported device.

Learn more about Leanpub's ebook formats and where to read them

Write and Publish on Leanpub

You can use Leanpub to easily write, publish and sell in-progress and completed ebooks and online courses!

Leanpub is a powerful platform for serious authors, combining a simple, elegant writing and publishing workflow with a store focused on selling in-progress ebooks.

Leanpub is a magical typewriter for authors: just write in plain text, and to publish your ebook, just click a button. (Or, if you are producing your ebook your own way, you can even upload your own PDF and/or EPUB files and then publish with one click!) It really is that easy.

Learn more about writing on Leanpub