thoughtbot/suspenders: A Rails Application Template for Heroku

What Suspenders generates, and who it is for

Suspenders is a Rails application template packaged as a gem. Running it produces a new Rails application preconfigured with thoughtbot's defaults, which the README describes as a jump start on new apps. It is aimed at teams that build conventional Rails products and deploy them to Heroku, which the README calls the recommended host. The generated app is opinionated from the first commit: PostgreSQL as the database, RSpec instead of the default test framework, and Sidekiq instead of the Solid ecosystem that ships with modern Rails.

The repository also carries FEATURES.md and GOALS.md, which is where the actual inventory of what gets generated lives. The README links to FEATURES.md rather than listing the contents, so anyone evaluating Suspenders should read that file directly instead of trusting the one-paragraph pitch. The gem is not a library you add to a Gemfile. It runs once, emits an application, and then the relationship mostly ends.

How the template actually runs under the hood

The README is explicit that Suspenders wraps Rails' own application template mechanism. The command it runs is a rails new invocation with a set of flags, and the template file is passed through the -m option. The visible flags are -d=postgresql, --skip-test and --skip-solid. Each one maps to a decision: PostgreSQL over SQLite or MySQL, no default test framework because RSpec is preferred, and no Solid Queue or Solid Cache because the README points to performance issues with Solid Queue on Heroku.

That means the data flow is one-directional. Suspenders does not sit between your app and Rails at runtime. It generates files, and after that your application is an ordinary Rails application. Upgrading Suspenders later will not retrofit anything into an existing project. This is the single most important thing to understand about the tool, and the README does not spell it out: there is no documented upgrade path for an application that was already generated.

Installing Suspenders and creating your first app

The README gives a two-step install. First the gem itself, then a Rails update, because Suspenders requires the latest version of Rails and its dependencies. PostgreSQL and Redis are listed as prerequisites, with Homebrew formulae linked for both, so they need to be running locally before you generate anything.

gem install suspenders

After the gem is on your machine, update Rails and then generate the application. The README asks for both steps in that order.

gem update rails

suspenders new <app_name>

The generator does not call its own private logic. According to the README, it runs Rails' application template command with a template file, and the flags shown there are the ones that decide PostgreSQL, no default test framework and no Solid stack.

rails new <app_name> \
 -d=postgresql \
 --skip-test \
 --skip-solid \
 --m=~/path/to/template.rb

One setup step is easy to miss. Because the generated application enables require_master_key, the README says you must add the key to GitHub as a secret or GitHub Actions will not work. The command it gives is run from inside the generated app.

cd <app_name>

gh secret set RAILS_MASTER_KEY value-from-config-master.key

The Heroku deployment path and the master key secret

Deployment is where Suspenders shows its Heroku bias. The README walks through the Heroku CLI: create the app, set the Ruby buildpack, add PostgreSQL and Redis addons, then set two required environment variables and scale a worker. The worker matters because Sidekiq is the queue, so a generated app without a running worker process will accept jobs and never process them.

cd <app_name>

heroku apps:create

heroku buildpacks:set heroku/ruby

heroku addons:create heroku-postgresql:essential-0
heroku addons:create heroku-redis:mini

Once the app is provisioned, the README lists two required environment variables and a worker scale command. Skipping the worker leaves Sidekiq jobs enqueued with nothing consuming them.

heroku config:set \
 APPLICATION_HOST=value-from-heroku \
 RAILS_MASTER_KEY=value-from-config-master.key

heroku ps:scale worker=1

The README also carries an important note about require_master_key. Because the generated application enables it, GitHub Actions will fail unless the master key is stored as a repository secret. The README gives the gh command for that. This is a real setup step that is easy to skip, and the failure mode is a red CI run rather than a helpful error at generation time.

Where Suspenders is the wrong tool

The clearest limitation is stated by the project itself: it skips the default test framework in favor of RSpec, and skips the Solid ecosystem in favor of Sidekiq. If your team writes Minitest, or wants Solid Queue and Solid Cache because you are deploying somewhere other than Heroku, the generated app is working against you. You would be deleting configuration rather than adding it, which is the opposite of what a template is for.

The second limitation is version coupling. Suspenders requires the latest Rails, so the generated app inherits whatever that version does. The README does not document rollback, and there is no described mechanism for pinning the template to an older Rails line. Teams maintaining a long-lived application on an older Rails version have no documented path through Suspenders.

Third, the README does not document what happens when you re-run the generator against an existing directory, so treat it as a one-shot scaffold.

How Suspenders differs from plain rails new and from Rails generators

The obvious alternative is rails new with your own flags, which is literally what Suspenders executes. The difference is that Suspenders packages a specific set of decisions, maintained by thoughtbot, into a template file rather than leaving each team to assemble flags and follow-up configuration. If your team already has its own application template, Suspenders is redundant, and running two templates over the same app is a recipe for conflicting configuration.

A second comparison point is Rails' built-in generators, which add pieces to an existing app. Suspenders does not do that. Generators are for incremental change inside a project; Suspenders is for the empty directory before the project exists. Choosing between them is really choosing whether you are starting fresh or modifying something that already runs.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-08-28. Releases are dated rather than semantic: v20260325.0, v20260213.0 and v20260105.0, all in 2026. That naming suggests a calendar-driven release cadence rather than a stability contract, so pinning a version in your notes is more useful than assuming a major version signals a breaking change.

Suspenders is MIT licensed and the README states it may be redistributed under the terms in the LICENSE file. The practical implication for generated apps is that the licence covers the template code, not your application, but the generated files are copies of template output, so teams with strict licence review processes should have their legal contact read LICENSE rather than assume. This is not legal advice, and the repository's LICENSE file is the only authoritative text.

Editorial conclusion

Adopt Suspenders if your next app is a standard Rails product on Heroku and your team already accepts RSpec, Sidekiq and PostgreSQL as settled choices. Skip it if you want Minitest, the Solid stack, or a non-Heroku host, because the generated app fights those defaults rather than supporting them. Before committing, read FEATURES.md and GOALS.md in the repository and confirm which Rails version the template currently targets, since the README only says the latest.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. thoughtbot/suspenders on GitHub