Inertia Rails Setup

Inertia Rails Setup

This skill helps you set up Inertia.js in a Ruby on Rails application with your choice of frontend framework.

Recommended: Official Starter Kits

For new projects, the fastest way to get started is cloning an official starter kit. These include authentication, shadcn/ui components, TypeScript, and optional SSR support out of the box.

React Starter Kit (Recommended)

git clone https://github.com/inertia-rails/react-starter-kit myapp
cd myapp
bin/setup

Includes:

• React 19 + TypeScript
• shadcn/ui component library (20+ components)
• User authentication (login, register, password reset)
• Settings pages (profile, password, email, sessions, appearance)
• Multiple layouts (sidebar, header, auth variants)
• Dark mode support
• Kamal deployment config
• Optional SSR support
• Flash messages with Sonner toasts

Vue Starter Kit

git clone https://github.com/inertia-rails/vue-starter-kit myapp
cd myapp
bin/setup

Svelte Starter Kit

git clone https://github.com/inertia-rails/svelte-starter-kit myapp
cd myapp
bin/setup

Customizing the Starter Kit

After cloning:

1. Rename the app:

```bash # Update config/application.rb module YourAppName class Application

### 4. Install Frontend Dependencies

**For React:**
```bash
npm install @inertiajs/react @inertiajs/vite react react-dom

For Vue 3:

npm install @inertiajs/vue3 @inertiajs/vite vue

For Svelte:

npm install @inertiajs/svelte @inertiajs/vite svelte

5. Configure the Frontend Entry Point

Create app/frontend/entrypoints/application.js:

React:

import { createInertiaApp } from '@inertiajs/react'
import { createRoot } from 'react-dom/client'
import { inertia } from '@inertiajs/vite'

createInertiaApp({
  resolve: inertia.resolvePages('../pages'),
  setup({ el, App, props }) {
    createRoot(el).render()
  },
})

Vue 3:

import { createApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import { inertia } from '@inertiajs/vite'

createInertiaApp({
  resolve: inertia.resolvePages('../pages'),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .mount(el)
  },
})

Svelte:

import { createInertiaApp } from '@inertiajs/svelte'
import { inertia } from '@inertiajs/vite'

createInertiaApp({
  resolve: inertia.resolvePages('../pages'),
  setup({ el, App }) {
    new App({ target: el })
  },
})

6. Create the Pages Directory

mkdir -p app/frontend/pages

7. Configure the Initializer

Create config/initializers/inertia_rails.rb:

# frozen_string_literal: true

InertiaRails.configure do |config|
  # Asset versioning
  config.version = -> { ViteRuby.digest }

  # Flash keys exposed to frontend
  config.flash_keys = %i[notice alert]

  # Required for Inertia.js v3
  config.use_script_element_for_initial_page = true
  config.use_data_inertia_head_attribute = true
  config.always_include_errors_hash = true

  # Deep merge shared data with page props
  # config.deep_merge_shared_data = true

  # Encrypt history for sensitive data (requires HTTPS)
  # config.encrypt_history = Rails.env.production?
end

8. Set Up Shared Data

In app/controllers/application_controller.rb:

class ApplicationController 
      {message}
    
  )
}

Page Component (Vue):

defineProps(['message'])

  
    {{ message }}
  

10. Start the Development Servers

# Terminal 1: Rails server
bin/rails server

# Terminal 2: Vite dev server
bin/vite dev

Configuration Options Reference

| Option | Default | Description | |--------|---------|-------------| | version | nil | Asset version for cache busting | | layout | 'application' | Default layout template | | flash_keys | [:notice, :alert] | Flash keys to share | | deep_merge_shared_data | false | Deep merge props | | encrypt_history | false | Encrypt browser history | | ssr_enabled | false | Enable SSR | | ssr_url | 'http://localhost:13714' | SSR server URL | | default_render | false | Auto-render Inertia | | root_dom_id | 'app' | Root element ID | | use_script_element_for_initial_page | false | Use ` tag for initial page data (required for v3) | | usedatainertiaheadattribute | false | Use data-inertia attribute for head tags (required for v3) | | alwaysincludeerrorshash | nil | Always include errors object in page props | | proptransformer | identity | Transform prop keys (e.g., camelCase) | | componentpathresolver | "path/action" | Custom component name resolution | | parentcontroller | '::ApplicationController' | Base controller for static routes | | exposesharedpropkeys | true | Include shared prop keys in page metadata | | precognitionpreventwrites | false` | Prevent DB writes during precognition |

Environment Variables

All config options can be set via INERTIA_ prefixed env vars:

INERTIA_SSR_ENABLED=true
INERTIA_ENCRYPT_HISTORY=true

Upgrading to Inertia.js v3

If upgrading an existing Inertia.js v2 project:

Required Configuration Changes

Add these to your Inertia Rails initializer:

config.use_script_element_for_initial_page = true
config.use_data_inertia_head_attribute = true
config.always_include_errors_hash = true

Breaking Changes

• React 19+ required
• Svelte 5+ with runes syntax required
• ES2022 build target required
• ESM-only — no CommonJS
• Axios removed — uses built-in XHR (use axiosAdapter() to keep Axios)
• Event renames: invalid → httpException, exception → networkError
• router.cancel() → router.cancelAll()
• Head attribute: inertia → data-inertia

Install the Vite Plugin

npm install @inertiajs/vite

Update vite.config.js:

import inertia from '@inertiajs/vite'

export default defineConfig({
  plugins: [
    inertia(),
    // ... other plugins
  ],
})

The Vite plugin provides:

• Automatic page component resolution
• Simplified SSR setup (no separate entry point in development)
• withApp callback for providers/plugins

Troubleshooting

"Cannot find module '@inertiajs/react'"

Run npm install to install dependencies.

Blank page with no errors

Check browser console for JavaScript errors. Ensure Vite dev server is running.

Props not updating

Ensure you're using render inertia: not render json:.

CSRF token errors

Inertia handles CSRF automatically. Ensure protect_from_forgery is enabled.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cole-robertson
• Source: cole-robertson/inertia-rails-skills
• License: MIT

Install and usage instructions live in the source repository linked above.