Rails Inertia Stack Generator

Overview

Generate complete, production-ready Rails applications with Inertia.js for SPA-like user experience, React + TypeScript frontend, Server-Side Rendering for SEO, ShadcnUI component library, and Kamal deployment configuration. The skill handles the entire setup process including Dockerfile configuration for SSR, database accessories, and deployment configuration.

When to Use This Skill

Use this skill when:

• Creating new Rails projects with modern frontend stack
• Setting up Inertia.js with React and TypeScript in Rails
• Configuring Server-Side Rendering for Rails + Inertia applications
• Setting up ShadcnUI with Rails projects
• Preparing Rails applications for Kamal deployment
• Migrating between databases (PostgreSQL/MySQL/SQLite)

Core Workflow

Step 1: Determine Project Requirements

Ask the user for project configuration:

• Project name (required)
• Database choice: PostgreSQL (recommended for production), MySQL, or SQLite
• Server IP addresses for deployment (can be configured later)
• Domain name for SSL (optional, can be configured later)

Step 2: Create Rails Project

Execute the appropriate Rails new command based on database choice:

PostgreSQL:

rails new PROJECT_NAME -d postgresql --skip-javascript
cd PROJECT_NAME

MySQL:

rails new PROJECT_NAME -d mysql --skip-javascript
cd PROJECT_NAME

SQLite:

# Default with Solid stack
rails new PROJECT_NAME --skip-javascript
cd PROJECT_NAME

# Or without Solid stack (if user requests)
rails new PROJECT_NAME --skip-javascript --skip-solid
cd PROJECT_NAME

Step 3: Install Inertia Rails Stack

Run these commands in sequence:

# Add Inertia Rails gem
bundle add inertia_rails

# Install frontend stack (non-interactive)
bin/rails generate inertia:install \
  --framework=react \
  --typescript \
  --vite \
  --tailwind \
  --no-interactive

When prompted about bin/dev conflict: Choose

Y

to overwrite.

After installation:

# Setup databases
bin/rails db:setup
bin/rails db:migrate

Step 4: Configure RuboCop (Optional but Recommended)

Rails 8 includes RuboCop Rails Omakase by default. Create or update

.rubocop.yml

:

# Omakase Ruby styling for Rails
inherit_gem: { rubocop-rails-omakase: rubocop.yml }

# Overwrite or add rules to create your own house style
#
# # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
# Layout/SpaceInsideArrayLiteralBrackets:
#   Enabled: false

# Restore strict 2-space indentation enforcement
Layout/IndentationConsistency:
  Enabled: true

Layout/IndentationWidth:
  Enabled: true
  Width: 2

Why this matters:

• Maintains consistent code style across the project
• Omakase provides sensible Rails defaults
• Strict 2-space indentation ensures readability

Step 5: Fix Development Configuration

Apply two critical fixes for development:

Fix 1: Procfile.dev (ensure Rails runs on port 3000)

Read

Procfile.dev

and swap the order:

web: bin/rails s
vite: bin/vite dev

Fix 2: config/vite.json (enable 127.0.0.1 access)

Add

"host": "127.0.0.1"

to development section:

{
  "development": {
    "autoBuild": true,
    "publicOutputDir": "vite-dev",
    "port": 3036,
    "host": "127.0.0.1"
  }
}

Step 6: Setup ShadcnUI

Configure TypeScript for ShadcnUI (CRITICAL: update BOTH files):

tsconfig.app.json - Add to compilerOptions:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./app/frontend/*"]
    }
  }
}

tsconfig.json - Add to root:

{
  "compilerOptions": {
    "baseUrl": "./app/frontend",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Initialize ShadcnUI (non-interactive):

npx shadcn@latest init --defaults --yes
npx shadcn@latest add button --yes --overwrite

Step 7: Configure Server-Side Rendering (SSR)

Create SSR entry point at

app/frontend/ssr/ssr.tsx

:

import { createInertiaApp } from '@inertiajs/react'
import createServer from '@inertiajs/react/server'
import ReactDOMServer from 'react-dom/server'

createServer((page) =>
  createInertiaApp({
    page,
    render: ReactDOMServer.renderToString,
    resolve: (name) => {
      const pages = import.meta.glob('../pages/**/*.tsx', { eager: true })
      return pages[`../pages/${name}.tsx`]
    },
    setup: ({ App, props }) => <App {...props} />,
  }),
)

Enable client-side hydration in

app/frontend/entrypoints/inertia.ts

:

Add

hydrateRoot

import:

import { createRoot, hydrateRoot } from 'react-dom/client'

Update setup function:

setup({ el, App, props }) {
  if (el) {
    if (import.meta.env.MODE === "production") {
      hydrateRoot(el, createElement(App, props))
    } else {
      createRoot(el).render(createElement(App, props))
    }
  } else {
    console.error('Missing root element...')
  }
}

Enable SSR in Vite - Add to

config/vite.json

:

{
  "production": {
    "ssrBuildEnabled": true
  }
}

Enable SSR in Inertia Rails - Update

config/initializers/inertia_rails.rb

:

InertiaRails.configure do |config|
  config.version = ViteRuby.digest
  config.encrypt_history = true
  config.always_include_errors_hash = true
  config.ssr_enabled = ViteRuby.config.ssr_build_enabled
end

Step 8: Configure Dockerfile for SSR

TWO modifications needed to the generated Dockerfile!

Reference

references/dockerfile-ssr-patterns.md

for complete examples.

Modification 1: Install Node.js in BASE stage

Add AFTER "Install base packages", BEFORE bundler installation:

# Install JavaScript runtime (prebuilt Node per-arch)
ARG NODE_VERSION=25.0.0
ARG TARGETARCH
ENV PATH=/usr/local/node/bin:$PATH
RUN apt-get update -qq && \
    apt-get install --no-install-recommends -y xz-utils && \
    case "${TARGETARCH}" in \
      amd64) NODEARCH=x64 ;; \
      arm64) NODEARCH=arm64 ;; \
      *) echo "Unsupported TARGETARCH: ${TARGETARCH}" >&2; exit 1 ;; \
    esac && \
    mkdir -p /usr/local/node && \
    curl -fsSL "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-${NODEARCH}.tar.xz" | \
      tar -xJ -C /usr/local/node --strip-components=1 && \
    /usr/local/node/bin/node -v && \
    /usr/local/node/bin/npm -v && \
    apt-get purge -y --auto-remove xz-utils && \
    rm -rf /var/lib/apt/lists /var/cache/apt/archives

Modification 2: Install Bundler with Locked Version

Add AFTER Node.js installation, BEFORE "Set production environment":

# Ensure the Bundler version matches Gemfile.lock to avoid per-build upgrades.
RUN gem install bundler -v 2.7.2 -N

Important: Check

Gemfile.lock

bottom section for

BUNDLED WITH

version and update to match:

tail Gemfile.lock
# BUNDLED WITH
#    2.7.2

That's all! No changes to BUILD stage (Vite Ruby handles npm install), no changes to final stage, no EXPOSE, no CMD modifications.

Database client variations - adjust base packages only:

• PostgreSQL:

  postgresql-client

  (base) and

  libpq-dev

  (build)
• MySQL:

  default-mysql-client

  (base) and

  libmysqlclient-dev

  (build)
• SQLite: No database client needed

Step 9: Configure Kamal Deployment

Update

config/deploy.yml

with SSR and database configuration.

Reference

references/kamal-ssr-deployment.md

and

references/complete-guide.md

for detailed examples.

Key additions:

1. Add

   vite

   server with

   init: true

   and

   network-alias: vite_ssr

   options
2. Add

   INERTIA_SSR_URL: http://vite_ssr:13714

   to env
3. Configure database accessory (PostgreSQL/MySQL) or volumes (SQLite)
4. Update database environment variables
5. (Optional) Add Redis/Valkey accessory if needed for caching, queues, or Action Cable

Redis/Valkey Configuration (if requested): Use Valkey instead of Redis due to licensing concerns:

accessories:
  redis:
    image: valkey/valkey:9  # Use Valkey, not redis image
    host: SERVER_IP
    port: "127.0.0.1:6379:6379"
    directories:
      - redis_data:/data

env:
  clear:
    REDIS_URL: redis://PROJECT_NAME-redis:6379/1

Solid Queue Configuration:

• If user created project WITH Solid (default), include:

  env:
    clear:
      SOLID_QUEUE_IN_PUMA: true
  

• If user created project with

  --skip-solid

  , OMIT this variable

Optional: Async Job Server (Advanced): For dedicated job processing (alternative to

SOLID_QUEUE_IN_PUMA

), add a job server:

servers:
  job:
    hosts:
      - SERVER_IP
    cmd: bundle exec async-job-adapter-active_job-server

This runs jobs in a separate container for better resource isolation.

Create database initialization file at

db/production.sql

:

CREATE DATABASE PROJECT_NAME_production_cache;
CREATE DATABASE PROJECT_NAME_production_queue;
CREATE DATABASE PROJECT_NAME_production_cable;

Update database.yml production section:

production:
  primary: &primary_production
    <<: *default
    host: <%= ENV["DB_HOST"] %>
    database: PROJECT_NAME_production
    username: PROJECT_NAME
    password: <%= ENV["POSTGRES_PASSWORD"] %>  # or MYSQL_ROOT_PASSWORD

Step 10: Test SSR Build

Verify the setup works:

export RAILS_ENV=production
./bin/rails assets:precompile

Check for successful output:

• Client bundle build completes
• SSR bundle build completes

• public/vite-ssr/ssr.js

  exists

Step 11: Provide Deployment Instructions

Inform the user about deployment configuration:

1. Configure secrets in

   .env

   (git-ignored):

   POSTGRES_PASSWORD=secure-password
   KAMAL_REGISTRY_PASSWORD=docker-hub-token
   

2. Update

   .kamal/secrets

   :

   KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
   RAILS_MASTER_KEY=$(cat config/master.key)
   POSTGRES_PASSWORD=$POSTGRES_PASSWORD
   

3. Update

   config/deploy.yml

   with actual server IPs and domain

4. Deploy:

   export $(grep -v '^#' .env | xargs)
   git add . && git commit -m "Setup Inertia Rails with SSR"
   kamal setup
   kamal deploy
   

Critical Patterns

Non-Interactive Installation

Always use these flags to avoid prompts:

# ShadcnUI initialization
npx shadcn@latest init --defaults --yes
npx shadcn@latest add COMPONENT --yes --overwrite

# Inertia installation
bin/rails generate inertia:install --no-interactive

SSR Build Process

• ✅ Use

  rails assets:precompile

  (handles both client and SSR, plus npm install)
• ❌ Do NOT run

  bin/vite build --ssr

  separately (redundant)
• ❌ Do NOT run

  npm ci

  separately (Vite Ruby handles it)

Dockerfile Node.js

• ✅ Install Node.js in base stage using prebuilt binaries (supports multi-arch)
• ✅ Node.js automatically included in final stage
• ❌ Do NOT remove Node.js after build (breaks SSR)
• ❌ Do NOT run npm ci separately (Vite Ruby handles it)

Kamal SSR Architecture

Web Container (Rails) ←→ vite_ssr Container (Node.js)
              via http://vite_ssr:13714

Fixed hostname via

network-alias: vite_ssr

enables reliable connection.

Database-Specific Variations

PostgreSQL (Production Recommended)

• Gem:

  pg

• Dockerfile client:

  postgresql-client

• Dockerfile build lib:

  libpq-dev

• Accessory image:

  postgres:18

  (latest stable)
• Volume mount:

  data:/var/lib/postgresql

  (BREAKING CHANGE in PostgreSQL 18: previous versions used

  data:/var/lib/postgresql/data

  )
• Port:

  127.0.0.1:5432:5432

• Env vars:

  POSTGRES_USER

  ,

  POSTGRES_DB

  ,

  POSTGRES_PASSWORD

MySQL

• Gem:

  mysql2

• Dockerfile client:

  default-mysql-client

• Dockerfile build lib:

  libmysqlclient-dev

• Accessory image:

  mysql:9.4.0

  (latest Innovation) or

  mysql:8.4

  (LTS recommended for production)
• Port:

  127.0.0.1:3306:3306

• Env vars:

  MYSQL_ROOT_HOST

  ,

  MYSQL_DATABASE

  ,

  MYSQL_USER

  ,

  MYSQL_ROOT_PASSWORD

SQLite (Development/Small Apps)

• Gem:

  sqlite3

  (default)
• Dockerfile: No database client needed
• Deployment: Use volumes instead of accessory
• Important: SQLite databases are stored in

  storage/

  directory in Rails 8+
• Volume configuration:

  # CORRECT: Mount storage directory (contains production.sqlite3)
  volumes:
    - "PROJECT_NAME_storage:/rails/storage"
  
  # INCORRECT: Do not mount db directory
  # volumes:
  #   - "PROJECT_NAME_db:/rails/db"
  

• Database location: Check

  config/database.yml

  production section for actual path:

  production:
    <<: *default
    database: storage/production.sqlite3  # Note: stored in storage/ not db/
  

Common Pitfalls to Avoid

1. Missing BOTH tsconfig updates - ShadcnUI requires updating both

   tsconfig.json

   and

   tsconfig.app.json

2. Interactive commands - Always use

   --defaults --yes

   with shadcn,

   --no-interactive

   with inertia:install
3. Removing Node.js from Dockerfile - Node.js must remain in production for SSR
4. Missing network-alias - Rails cannot connect to SSR without

   network-alias: vite_ssr

5. Wrong Procfile.dev order - Vite first causes Rails to run on port 3100 instead of 3000
6. Missing vite.json host - Without

   "host": "127.0.0.1"

   , connections to 127.0.0.1 fail
7. Not updating database.yml - Must add

   host: <%= ENV["DB_HOST"] %>

   and password for production
8. Wrong SQLite volume path - Must mount

   /rails/storage

   (not

   /rails/db

   ) since Rails 8 stores SQLite in storage/ directory
9. Using Redis image instead of Valkey - Use

   valkey/valkey:9

   image to avoid Redis licensing concerns
10. Bundler version mismatch - Must lock bundler version in Dockerfile to match

    Gemfile.lock

    to prevent cache invalidation

Troubleshooting

SSR Build Fails

• Check Node.js is in Dockerfile base stage
• Verify

  config/vite.json

  has

  "ssrBuildEnabled": true

• Ensure

  app/frontend/ssr/ssr.tsx

  exists
• Run

  npm ci

  to reinstall dependencies

Rails Can't Connect to SSR

• Verify

  vite

  server has

  network-alias: vite_ssr

  in deploy.yml
• Check

  INERTIA_SSR_URL: http://vite_ssr:13714

  in env
• Ensure both web and vite containers are on same network

Database Connection Fails

• Verify

  DB_HOST

  matches accessory service name (e.g.,

  PROJECT_NAME-db

  )
• Check database accessory is running:

  kamal accessory details db

• Confirm password matches between

  .kamal/secrets

  and

  config/database.yml

ShadcnUI Components Not Resolving

• Verify BOTH tsconfig files have path aliases
• Ensure imports use

  @/

  prefix:

  import { Button } from '@/components/ui/button'

Resources

references/

• complete-guide.md

  - Complete 778-line implementation guide with all variations

• dockerfile-ssr-patterns.md

  - Dockerfile modifications for PostgreSQL/MySQL/SQLite

• kamal-ssr-deployment.md

  - Kamal SSR architecture and deployment examples

assets/

• ssr-entry.tsx

  - SSR server entry point template

• deploy-postgres.yml

  - PostgreSQL deployment configuration

• deploy-mysql.yml

  - MySQL deployment configuration

• deploy-sqlite.yml

  - SQLite deployment configuration

Use these references when detailed examples are needed or when helping users with specific database configurations.