The complete guide to `rails new` in Rails 8.1

rails new --help prints 30+ options. Most tutorials stop at rails new myapp -d postgresql and move on. This post covers every Rails 8.1 option - what it does, when to use it, and what most people pick.

App Mode

--api - Strips views, cookies, sessions, asset pipeline, Hotwire, CSS, and JavaScript. Use for pure JSON or GraphQL backends.

--minimal - Generates the smallest possible app. Skips Action Mailer, Action Mailbox, Action Text, Active Job, Active Storage, Action Cable, Hotwire, Jbuilder, tests, system tests, Kamal, Thruster, Solid, and Bootsnap. A good starting point when you want to add only what you need.

Database (--database=X)

Adapter	Pros	Cons	Best for
sqlite3 (default)	Zero setup, no server, works with Solid stack. 37signals runs ONCE products on it in production.	Single-writer, no multi-server scaling.	Solo devs, prototypes, single-server apps
postgresql ⭐	Full-featured (JSONB, arrays, full-text search), every PaaS supports it, best managed DB options.	Requires a running server.	Most production apps
mysql	Widely deployed, mature.	No native arrays, JSON can't be indexed directly (unlike PostgreSQL's JSONB).	Existing MySQL infrastructure
trilogy	Modern MySQL client by GitHub, no C library dependency, simpler install. GitHub & Shopify use it in production.	Newer, smaller ecosystem.	New MySQL projects
mariadb-mysql	For MariaDB specifically with mysql2 adapter.	Same as mysql.	Existing MariaDB setups
mariadb-trilogy	For MariaDB specifically with Trilogy adapter.	Same as trilogy.	New MariaDB projects

PostgreSQL is the most common choice. When in doubt, pick it.

--skip-active-record / -O - Drops the ORM entirely. Cascading effect: also skips database, Action Mailbox, Action Text, and Active Storage.

Frontend Stack

JavaScript (--javascript=X / -j)

Approach	Pros	Cons	Best for
importmap (default) ⭐	No Node.js, no build step, browser-native ES modules, HTTP/2 parallel downloads.	No tree-shaking, no TypeScript/JSX transpilation.	Standard Rails + Hotwire apps
esbuild	Extremely fast (Go-based), handles TypeScript/JSX, mature.	Requires Node.js.	Apps needing a bundler
bun	~1.75x faster than esbuild, doubles as package manager + bundler.	Newer, smaller ecosystem than esbuild.	Speed-first, Bun ecosystem
webpack	Full-featured, huge plugin ecosystem.	Slow, complex config, legacy choice.	Not recommended for new projects
rollup	Good for libraries, ES module focused.	Niche in Rails context.	Not recommended for new projects

Importmap is the Rails default for a reason - it eliminates Node.js from your stack entirely. Reach for esbuild or bun only when you need TypeScript, JSX, or tree-shaking.

--skip-javascript / -J - No JS setup at all.

CSS (--css=X / -c)

Framework	Pros	Cons	Best for
(none) (default)	No dependencies, write plain CSS.	No utilities or components.	Minimal apps, custom design systems
tailwind ⭐	Rails-blessed (tailwindcss-rails gem), no Node.js required, v4 is 5x faster with CSS-first config.	Verbose HTML classes, learning curve.	Most new Rails apps
bootstrap	Pre-built components, familiar to most devs.	Requires Node.js (via cssbundling-rails), heavier.	Apps needing ready-made UI components
bulma	CSS-only (no JS), clean modern design.	Requires Node.js via cssbundling-rails, smaller community.	Lightweight component needs
postcss	Plugin-based CSS transforms, flexible.	Requires Node.js, config overhead.	Custom CSS toolchains
sass	Variables, nesting, mixins, mature.	Requires Node.js (Propshaft doesn't compile Sass).	Teams already using Sass

No CSS framework is included by default. Tailwind is the most popular choice for new Rails apps - the tailwindcss-rails gem runs standalone, no Node.js required.

Asset Pipeline (--asset-pipeline=X)

Pipeline	Pros	Cons
propshaft (default) ⭐	Modern, lightweight - just fingerprinting and serving. Precompiles in seconds vs minutes.	No built-in preprocessing (delegates to external tools).
sprockets	Built-in Sass/CoffeeScript/ERB compilation, //= require directives.	Slow, complex, legacy.

Propshaft does one thing well: fingerprint and serve assets. If you need Sass or CoffeeScript compilation, Sprockets handles it - but you probably don't in 2025.

--skip-asset-pipeline / -A - No asset pipeline at all.

Hotwire (--skip-hotwire)

Turbo + Stimulus - the default Rails frontend framework. Turbo 8 introduced morphing (DOM diffing via idiomorph) that makes full-page refreshes feel SPA-smooth. Skip only if you're using a JS SPA framework (React, Vue) or building an API-only app (auto-skipped with --api).

The Solid Stack & Deployment

These are Rails 8 additions that replace external services with database-backed alternatives.

--skip-solid

Solid Cache + Solid Queue + Solid Cable - replaces Redis for caching, background jobs, and WebSockets. All database-backed, works with SQLite, PostgreSQL, and MySQL. 37signals runs 20M jobs/day on Solid Queue for HEY.

• Solid Cache - database-backed caching. Higher latency than Redis RAM, but terabytes of SSD capacity at a fraction of the cost.
• Solid Queue - uses FOR UPDATE SKIP LOCKED for efficient polling. Replaces Sidekiq/Resque for most apps.
• Solid Cable - database-backed Action Cable. Polls every 100ms. Fine for moderate real-time needs.

Skip if: you already run Redis and need Sidekiq's advanced features (batches, rate limiting) or sub-millisecond cache latency.

--skip-kamal

Kamal 2 deploys Docker containers to any VPS (Hetzner, DigitalOcean, AWS EC2). Uses kamal-proxy (replaces Traefik) with automatic Let's Encrypt SSL. Zero-downtime deploys, rolling restarts.

Skip if: you deploy to a PaaS (Heroku, Render, Fly.io) or use Kubernetes.

--skip-thruster

Thruster - HTTP/2 proxy (written in Go by 37signals) that sits in front of Puma. Provides HTTP/2, gzip compression, asset caching, X-Sendfile, and automatic SSL. Replaces Nginx/Caddy for simple deployments.

Skip if: you already have a reverse proxy (Nginx, ALB, Cloudflare) or deploy to a PaaS.

Frameworks You Can Skip

Email & Rich Content

--skip-action-mailer / -M - No email sending or receiving infrastructure. Skip if your app never sends email.

--skip-action-mailbox - No inbound email routing to controller-like mailboxes. Requires Active Record. Skip if you don't process incoming email.

--skip-action-text - No Trix rich text editor integration. Requires Active Record. Auto-skipped in API mode.

Background & Storage

--skip-active-job - No background job framework. Also disables Solid Queue integration. Skip only if you handle no async work at all.

--skip-active-storage - No file uploads to S3/GCS/Azure. Requires Active Record. Skip if your app handles no file uploads.

--skip-action-cable / -C - No WebSocket framework. Also disables Solid Cable. Skip if you don't need real-time features.

JSON

--skip-jbuilder - Removes the Jbuilder JSON template DSL. Most API apps prefer render json: with serializers instead.

Testing & Code Quality

--skip-test / -T - Removes Minitest setup. Most people skip this to add RSpec instead.

--skip-system-test - Skips Capybara browser tests. Auto-skipped in API mode or when tests are skipped.

--skip-brakeman - Brakeman is a static security scanner for Rails that catches SQL injection, XSS, and 33+ other vulnerability types. Runs in seconds. Keep it.

--skip-bundler-audit - New in Rails 8.1. bundler-audit scans your Gemfile.lock for gems with known CVEs. Complements Brakeman: code scanning + dependency scanning. Keep it.

--skip-rubocop - RuboCop, Ruby linter, included by default since Rails 8. Keep it or swap in Standard Ruby.

--skip-ci - Skips the generated GitHub Actions workflow. Rails 8.1 CI includes Brakeman and Bundler Audit steps by default.

Infrastructure & Housekeeping

--skip-docker - Skips Dockerfile, .dockerignore, and bin/docker-entrypoint. Skip if you're not containerizing.

--devcontainer - Opt-in (not included by default). Generates VS Code dev container config with Redis, database, and Ruby all preconfigured.

--skip-bootsnap - Bootsnap caches expensive computations to speed up boot time. Rarely worth skipping.

--skip-dev-gems - Skips web-console and similar development gems.

--skip-keeps - Skips .keep files in empty directories. Git doesn't track empty dirs, so .keep files exist to preserve the directory structure.

--skip-decrypted-diffs - Skips git config for showing decrypted diffs of encrypted credentials.

--skip-git / -G - Skips git init, .gitignore, and .gitattributes.

--skip-bundle / -B - Skips bundle install after generation. Useful in CI or Docker builds where you control dependency installation separately.

Putting It Together - Common Recipes

Full-stack SaaS:

rails new myapp -d postgresql -c tailwind -T \
  --skip-action-mailbox --skip-action-text --skip-jbuilder

The workhorse setup. PostgreSQL, Tailwind, Solid stack, Kamal - all defaults. Skips Minitest (most teams add RSpec), Action Mailbox (few apps process incoming email), Action Text (add it later if you need a rich text editor), and Jbuilder (you'll use render json: or a serializer).

API backend:

rails new myapi --api -d postgresql -T \
  --skip-action-mailbox --skip-jbuilder

--api strips views, assets, cookies, and Hotwire. Skips Minitest for RSpec. Action Mailbox and Jbuilder rarely belong in an API.

Single-server indie app (the "one person framework"):

rails new myapp -d sqlite3 -c tailwind -T \
  --skip-action-mailbox --skip-action-text --skip-jbuilder

SQLite + Solid stack = no Redis, no PostgreSQL, no external services. Kamal and Thruster handle deployment and SSL. One server, one process, one database file. Add PostgreSQL later if you outgrow it.

PaaS deploy (Heroku, Render, Fly.io):

rails new myapp -d postgresql -c tailwind -T \
  --skip-action-mailbox --skip-action-text --skip-jbuilder \
  --skip-kamal --skip-thruster

Same as the SaaS setup but skips Kamal and Thruster - the PaaS handles containers, routing, and SSL for you.

Lean prototype:

rails new proto --minimal -d sqlite3

Bare minimum: no mailer, no jobs, no cable, no Hotwire, no Kamal. Add frameworks back as you need them.

---

If you don't want to memorize any of this, I built a tool for that. create-rails-app is an interactive CLI wizard that walks you through each option, remembers your choices, and saves reusable presets.

gem install create-rails-app