| name | inertia-rails-setup |
| description | Set up a new Inertia Rails project or add Inertia to an existing Rails application. Use when creating new projects, configuring Inertia, or setting up the development environment with React, Vue, or Svelte. |
| license | MIT |
| metadata | {"author":"community","version":"2.0.0"} |
| user-invocable | true |
| argument-hint | [react|vue|svelte] [--typescript] [--tailwind] |
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:
-
Rename the app:
module YourAppName
class Application < Rails::Application
-
Update database config:
-
Remove example pages you don't need:
-
Add your own pages:
bin/rails generate controller Products index show
-
Customize the layout:
- Edit
app/frontend/layouts/app-layout.tsx for main app
- Edit
app/frontend/components/nav-main.tsx for navigation
Alternative: Generator Setup
If you prefer starting from scratch or adding Inertia to an existing Rails app:
Quick Setup
rails new myapp --skip-javascript
bundle add inertia_rails
bin/rails generate inertia:install
The generator will prompt you to select:
- Frontend framework (React, Vue, or Svelte)
- TypeScript support
- Tailwind CSS integration
Manual Setup Steps
1. Add the Gem
gem 'inertia_rails'
bundle install
2. Install Vite Rails (if not present)
bundle add vite_rails
bundle exec vite install
3. Configure the Root Layout
Create or update app/views/layouts/application.html.erb:
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width,initial-scale=1">
<%= csp_meta_tag %>
<%= inertia_ssr_head %>
<%= vite_client_tag %>
<%= vite_javascript_tag 'application' %>
</head>
<body>
<%= yield %>
</body>
</html>
4. Install Frontend Dependencies
For React:
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(<App {...props} />)
},
})
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:
InertiaRails.configure do |config|
config.version = -> { ViteRuby.digest }
config.flash_keys = %i[notice alert]
config.use_script_element_for_initial_page = true
config.use_data_inertia_head_attribute = true
config.always_include_errors_hash = true
end
8. Set Up Shared Data
In app/controllers/application_controller.rb:
class ApplicationController < ActionController::Base
inertia_share do
{
flash: {
notice: flash.notice,
alert: flash.alert
},
auth: {
user: current_user&.as_json(only: [:id, :name, :email])
}
}
end
end
9. Create Your First Page
Controller:
class HomeController < ApplicationController
def index
render inertia: { message: 'Welcome to Inertia Rails!' }
end
end
Route:
Rails.application.routes.draw do
root 'home#index'
end
Page Component (React):
export default function Home({ message }) {
return (
<div>
<h1>{message}</h1>
</div>
)
}
Page Component (Vue):
<!-- app/frontend/pages/home/index.vue -->
<script setup>
defineProps(['message'])
</script>
<template>
<div>
<h1>{{ message }}</h1>
</div>
</template>
10. Start the Development Servers
bin/rails 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 <script> tag for initial page data (required for v3) |
use_data_inertia_head_attribute | false | Use data-inertia attribute for head tags (required for v3) |
always_include_errors_hash | nil | Always include errors object in page props |
prop_transformer | identity | Transform prop keys (e.g., camelCase) |
component_path_resolver | "path/action" | Custom component name resolution |
parent_controller | '::ApplicationController' | Base controller for static routes |
expose_shared_prop_keys | true | Include shared prop keys in page metadata |
precognition_prevent_writes | 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(),
],
})
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.
