Options
Every question the tool asks, what the choices do, and what each one adds to your app. The config file key for each is in Config file. The dependency order the steps run in is in the step reference.
Table of contents
Always included
Whatever you choose, every app gets:
AGENT.mdandSTYLE.md: a short project style guide for people and coding agents.- GitHub pull request and issue templates (
.github/PULL_REQUEST_TEMPLATE.md,.github/ISSUE_TEMPLATE/). - Faker in the development and test groups.
- A
Dockerfileand.dockerignore, generated bydockerfile-rails(Rails’ own Docker and Kamal files are skipped in favour of these).
App name
The directory and application name. Hyphens become underscores. It must be a valid Ruby constant once camelized, must not start with a digit, and must not be a reserved name such as test or application. The directory must not already exist.
Database
SQLite (default), PostgreSQL or MySQL. Passed to rails new as --database.
- With PostgreSQL or MySQL, the generated CI starts a matching service container, and Kamal takes
DATABASE_URLas a secret. - With SQLite, Kamal gets a persistent volume for the database (it lives in
/datain the Docker image).
App type
Full-stack (default) or API-only (rails new --api). API-only apps get no frontend, SPA controller, Tailwind or JavaScript linting, and authentication is skipped.
Test framework
Minitest (default) or RSpec. RSpec installs rspec-rails in the development and test group, runs rspec:install, and the generated CI runs bundle exec rspec. Minitest runs bin/rails test.
Frontend
Stimulus + Hotwire (default): Rails’ importmap setup, plus Tailwind CSS through tailwindcss-rails, which is built once at generation so the first bin/rails test passes. Unknown paths render a “Not Found” page through a catch-all route.
React: choose a bundler and get React 18, React Router and a mount point.
| Bundler | Notes |
|---|---|
esbuild (default) |
Needs yarn. JSX is handled natively. The @ import alias points at app/javascript |
webpack |
Needs yarn. Babel (with the React preset) is added so .jsx builds. The @ alias is configured |
bun |
Needs bun. The entry point in bun.config.js is set to application.jsx (Bun builds JSX natively). The @ alias is for editors only until you add bundler config |
React apps also get:
app/javascript/application.jsxandrouter.jsx, andjsconfig.json.- A SPA controller.
/and any HTML path that no other route matches render a page with<div id="root">. - Tailwind CSS through the Tailwind 3 CLI (
build:cssscript, configured inconfig/tailwind.config.js). - The JavaScript and CSS built at generation, so the first page load does not fail on missing assets.
Rollup is not offered: Rails’ rollup config expects application.js and has no JSX transform, so it cannot build what the React option writes.
RuboCop
Omakase (default) uses Rails’ rubocop-rails-omakase. Custom adds an overrides section to .rubocop.yml that you can edit. Either way the generator applies RuboCop’s safe autocorrect at the end, so bin/rubocop passes on the first run.
Jobs, cache and cable
Solid Trifecta (default): Rails 8’s Solid Queue, Solid Cache and Solid Cable, backed by your database. On a single Kamal server, jobs run inside Puma.
Redis + Sidekiq: replaces the Solid trio entirely. The generator removes the Solid gems, their config files and their database.yml blocks, points the cache store, Active Job and Action Cable at Redis, and writes a Sidekiq initializer. Sidekiq::Web is left unmounted (as a commented route) because it has no authentication of its own.
In production, REDIS_URL must be set or the app refuses to boot with REDIS_URL is not set. The Docker asset precompile, which has no Redis, is exempt.
Pagination
pagy (default): adds pagy, an initializer, and include Pagy::Method in ApplicationController. geared_pagination adds the gem only.
Staging environment
Adds config/environments/staging.rb, copied from production, and a staging: block in database.yml, cable.yml, cache.yml and queue.yml (names ending in _staging, not your production ones).
Staging uses the :test mail delivery method, so it cannot send real email through your production Postmark account. The file explains how to give staging its own Postmark server.
Application services
Adds app/services/application_service.rb and app/services/result.rb: a small service-object base class with a Result type (success?, failure?, data, errors) and a transaction helper.
Secrets
Rails credentials (default) uses config/credentials.yml.enc. The tool warns if config/master.key is missing. dotenv adds dotenv-rails (development and test only), a committed .env.example, and makes sure .env is git-ignored while .env.example stays tracked. With dotenv, the mailer reads POSTMARK_API_TOKEN from the environment.
Authentication
| Choice | What you get |
|---|---|
none (default) |
Nothing |
rails8 |
Rails 8’s built-in generator: User and Session models, sessions and passwords controllers. A minimal HomeController and root route are added (React apps use the SPA root instead), because the generated sign-in redirects to root_url |
devise |
The devise gem, devise:install, your model (auth_model, default User) and the Devise views |
API-only apps skip authentication and print a notice. Rails’ built-in generator and Devise both emit browser-session code that needs cookies and views, which an API app does not have.
auth_model only affects Devise. The Rails 8 generator always creates User.
Factories
RSpec only. FactoryBot (default) adds factory_bot_rails and spec/factories. Fixtures keeps Rails’ fixtures.
VCR
Adds vcr and webmock, a support file that configures cassettes (spec/cassettes or test/cassettes) with a starter filter_sensitive_data for API_KEY, and wires it into your test helper. Extend the filters for your own secrets before recording cassettes.
JavaScript linting
Asked whenever the app has a frontend. Adds ESLint 9 with a flat config (eslint.config.js) and a lint:js script. For React it adds the React and React Hooks plugins and lints both .js and .jsx. CI gets a matching js_lint job.
Docker and Kamal
A Dockerfile is always generated. Answering yes to Kamal also adds the kamal gem and complete config/deploy.yml and .kamal/secrets files for your stack. See Deploying.
CI
A GitHub Actions workflow with jobs for tests, RuboCop, security scans (Brakeman and bundler-audit) and, when linting is on, JavaScript lint. It has read-only token permissions, cancels superseded runs, sets timeouts, and starts PostgreSQL, MySQL or Redis service containers to match your choices. See The generated app.
Mailer
Letter Opener in development and Postmark in production (postmark-rails). The Postmark token comes from Rails credentials, or from POSTMARK_API_TOKEN with dotenv. Set the from address and default_url_options host before sending mail.