Inertia Rails Starter Kit

A modern full-stack starter application with Rails backend and React frontend using Inertia.js based on the Laravel Starter Kit and Inertia Rails Starter Kit.

Features

• Inertia Rails & Vite Rails setup
• React frontend with TypeScript & shadcn/ui component library
• Clerk User authentication system
• Email delivery with Resend (production) and letter_opener (development)
• Kamal for deployment
• Optional SSR support

Setup

1. Clone this repository
2. Run the setup script:

   bin/setup

   bin/setup is idempotent and will, in order:
   • Install Ruby (Bundler) and JavaScript (npm) dependencies.
   • Create a .env file from .env.example if one doesn't already exist.
   • Make sure your Rails encrypted credentials can be decrypted (see Rails Credentials & the Master Key).
   • Prepare the database and clear old logs/tempfiles.
   • Start the development server (pass --skip-server to stop before this).
3. Fill in your secrets (the script will remind you at the end):
   • Edit .env and set VITE_CLERK_PUBLISHABLE_KEY (and any other keys you need).
   • Edit your Rails credentials with bin/rails credentials:edit (Clerk secret_key / webhook_secret, Resend api_key, etc.).
   • See Environment Variables for the full list.
4. Open http://localhost:3000

What you need before you start

• Ruby and Node.js matching the versions in .ruby-version and .tool-versions.
• A Clerk account for authentication (sign up) — you'll need a publishable key (for .env) and a secret key (for Rails credentials).
• The Rails master key for this app's encrypted credentials. The encrypted config/credentials.yml.enc is committed to the repo, but config/master.key is intentionally not (it's gitignored). See below.

Rails Credentials & the Master Key

Rails stores secrets in an encrypted file, config/credentials.yml.enc, which is decrypted with config/master.key (or the RAILS_MASTER_KEY environment variable). The master key is gitignored and never committed, so a fresh clone has the encrypted file but no key to read it.

bin/setup detects this situation and offers three choices:

1. Enter the existing master key — paste the key shared securely by a teammate (or your secrets manager). The script writes it to config/master.key.
2. Delete and regenerate — permanently deletes the existing config/credentials.yml.enc, then runs bin/rails credentials:edit to create a brand new master key and credentials file. Use this if you don't have the original key (e.g. you're starting your own project from this template). You'll need to re-add every secret afterwards — see config/credentials.yml.example for the expected structure.
3. Skip — leave it for now and fix it manually before booting the app.

You can also set RAILS_MASTER_KEY in your environment instead of using a config/master.key file (recommended for production / CI).

To view or edit credentials at any time:

bin/rails credentials:edit

Environment Variables

This application requires the following environment variables for proper functionality:

Required for Development & Production

Clerk Authentication

• VITE_CLERK_PUBLISHABLE_KEY - Your Clerk publishable key (starts with pk_test_ or pk_live_)
  • Get this from your Clerk Dashboard
  • Add to your .env file for development
  • Required for frontend authentication components

Rails Credentials

The following secrets should be added to Rails encrypted credentials using rails credentials:edit:

clerk:
  api_key: "sk_test_your_secret_key_here"  # Your Clerk secret key

# For production email delivery
resend:
  api_key: "your_resend_api_key_here"

Email Delivery

• FROM_EMAIL - Email address used as sender for all outgoing emails
  • Must use a verified domain in your Resend account for production
  • Default: noreply@example.com
• HOST - Your application's domain name for generating links in emails (production)

Email Setup: This application uses Resend for production email delivery and letter_opener for development email preview.

Development: No setup required - emails automatically open in your browser.

Production Setup:

1. Sign up for a Resend account and create an API key
2. Add your Resend API key to Rails credentials:

   rails credentials:edit

   Add:

   resend:
     api_key: "your_resend_api_key_here"

3. Set environment variables:

   FROM_EMAIL=noreply@yourdomain.com
   HOST=yourdomain.com

4. Verify your sending domain in your Resend account

Optional Environment Variables

Error Tracking (Sentry)

• SENTRY_DSN - Sentry Data Source Name for backend error tracking
  • Get this from your Sentry project settings
  • Only active in production environment
  • Required for backend error tracking
• VITE_SENTRY_DSN - Sentry DSN for frontend error tracking
  • Same DSN as backend, but exposed to frontend via Vite
  • Only active in production builds (npm run build)
  • Required for frontend error tracking
• SENTRY_TRACES_SAMPLE_RATE - Sample rate for performance monitoring (default: 0.1)
• VITE_SENTRY_TRACES_SAMPLE_RATE - Frontend sample rate for performance monitoring (default: 0.1)

Database

• DATABASE_URL - PostgreSQL connection string (production)
• Default: SQLite in development

Rails

• RAILS_ENV - Application environment (development, test, production)
• SECRET_KEY_BASE - Rails secret key base (auto-generated in development)

Deployment (Kamal)

• KAMAL_REGISTRY_PASSWORD - Docker registry password
• KAMAL_REGISTRY_USERNAME - Docker registry username
• Server-specific variables as configured in config/deploy.yml

Setting Up Clerk

1. Create a Clerk account
2. Create a new application in your Clerk dashboard
3. Copy the publishable key to VITE_CLERK_PUBLISHABLE_KEY in your .env file
4. Copy the secret key to Rails credentials using rails credentials:edit
5. Configure your Clerk application settings (sign-in methods, appearance, etc.)

Setting Up Clerk Webhooks

This application uses Clerk webhooks to automatically sync user data changes. To set up webhooks:

1. In your Clerk dashboard, go to Webhooks
2. Create a new webhook endpoint with the URL: https://your-domain.com/webhooks/clerk
3. Select the following events:
   • user.deleted - Automatically deletes users from your database when deleted in Clerk
   • user.updated - Clears user cache when profile is updated in Clerk
4. Copy the webhook signing secret to Rails credentials:

   rails credentials:edit

   Add the webhook secret:

   clerk:
     secret_key: "sk_test_your_secret_key_here"
     publishable_key: "pk_test_your_publishable_key_here"
     webhook_secret: "whsec_your_webhook_secret_here"

Note: The webhook endpoint automatically handles user deletion from your platform when users delete their accounts through Clerk's user interface, eliminating the need for manual account deletion components.

Setting Up Sentry Error Tracking

This application includes integrated error tracking with Sentry for both backend and frontend.

Important: Sentry is only enabled in production to avoid noise during development.

1. Create a Sentry account and create a new project
2. Copy your project's DSN from the project settings
3. Set the following environment variables:
   • SENTRY_DSN - For backend error tracking
   • VITE_SENTRY_DSN - For frontend error tracking (same value as above)
4. Optional: Configure sample rates:
   • SENTRY_TRACES_SAMPLE_RATE - Backend performance monitoring (default: 0.1)
   • VITE_SENTRY_TRACES_SAMPLE_RATE - Frontend performance monitoring (default: 0.1)

Sentry will automatically:

• Track errors and exceptions in both Rails and React
• Monitor performance and capture traces
• Provide session replay for frontend errors
• Tag releases with Git commit hash (useful for Heroku deployments)

Heroku Deployment with Sentry

For Heroku deployments, you'll need to enable the Heroku Labs runtime-dyno-metadata feature to automatically track Git commit information with your Sentry releases:

# Enable the runtime-dyno-metadata lab feature
heroku labs:enable runtime-dyno-metadata -a your-app-name

# Set your Sentry DSN environment variables
heroku config:set SENTRY_DSN="https://your-dsn@o123456.ingest.sentry.io/123456" -a your-app-name
heroku config:set VITE_SENTRY_DSN="https://your-dsn@o123456.ingest.sentry.io/123456" -a your-app-name

This feature provides the HEROKU_SLUG_COMMIT environment variable that Sentry uses to automatically tag releases with the deployed Git commit hash, making it easier to track which version of your code is running and correlate errors with specific deployments.

Example .env file

# Clerk Configuration
VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

# Sentry Error Tracking (Production only)
# SENTRY_DSN=https://your-dsn@o123456.ingest.sentry.io/123456
# VITE_SENTRY_DSN=https://your-dsn@o123456.ingest.sentry.io/123456

# Email Configuration (production)
# FROM_EMAIL=noreply@yourdomain.com
# HOST=yourdomain.com

# Optional: Database (defaults to SQLite in development)
# DATABASE_URL=postgresql://user:password@localhost/myapp_development

Enabling SSR

This starter kit comes with optional SSR support. To enable it, follow these steps:

1. Open app/frontend/entrypoints/inertia.ts and uncomment part of the setup function:

   // Uncomment the following to enable SSR hydration:
   // if (el.hasChildNodes()) {
   //   hydrateRoot(el, createElement(App, props))
   //   return
   // }

2. Open config/deploy.yml and uncomment several lines:

   servers:
     # Uncomment to enable SSR:
     # vite_ssr:
     #   hosts:
     #     - 192.168.0.1
     #   cmd: bundle exec vite ssr
     #   options:
     #     network-alias: vite_ssr
      
   # ...
      
   env:
     clear:
       # Uncomment to enable SSR:
       # INERTIA_SSR_ENABLED: true
       # INERTIA_SSR_URL: "http://vite_ssr:13714"
      
   # ...
      
   builder:
     # Uncomment to enable SSR:
     # dockerfile: Dockerfile-ssr

That's it! Now you can deploy your app with SSR support.

License

The project is available as open source under the terms of the MIT License.