Responses
Creating responses
Creating an Inertia response is simple. To get started, just use the inertia
renderer in your controller methods, providing both the name of the JavaScript page component that you wish to render, as well as any props (data) for the page.
class EventsController < ApplicationController
def show
event = Event.find(params[:id])
render inertia: 'Event/Show', props: {
event: event.as_json(
only: [:id, :title, :start_date, :description]
)
}
end
end
Within Rails applications, the Event/Show
page would typically correspond to the file located at app/frontend/pages/Event/Show.(jsx|vue|svelte)
.
WARNING
To ensure that pages load quickly, only return the minimum data required for the page. Also, be aware that all data returned from the controllers will be visible client-side, so be sure to omit sensitive information.
Using instance variables as props
Inertia enables the automatic passing of instance variables as props. This can be achieved by invoking the use_inertia_instance_props
function in a controller or in a base controller from which other controllers inherit.
class EventsController < ApplicationController
use_inertia_instance_props
def index
@events = Event.all
render inertia: 'Events/Index'
end
end
This action automatically passes the @events
instance variable as the events
prop to the Events/Index
page component.
NOTE
Manually providing any props for a response disables the instance props feature for that specific response.
NOTE
Instance props are only included if they are defined after the use_inertia_instance_props
call, hence the order of before_action
callbacks is crucial.
Automatically determine component name
Rails conventions can be used to automatically render the correct page component by invoking render inertia: true
:
class EventsController < ApplicationController
use_inertia_instance_props
def index
@events = Event.all
render inertia: true
end
end
This renders the app/frontend/pages/events/index.(jsx|vue|svelte)
page component and passes the @events
instance variable as the events
prop.
Setting the default_render
configuration value to true
establishes this as the default behavior:
InertiaRails.configure do |config|
config.default_render = true
end
class EventsController < ApplicationController
use_inertia_instance_props
def index
@events = Event.all
end
end
With this configuration, the app/frontend/pages/events/index.(jsx|vue|svelte)
page component is rendered automatically, passing the @events
instance variable as the events
prop.
Root template data
There are situations where you may want to access your prop data in your ERB template. For example, you may want to add a meta description tag, Twitter card meta tags, or Facebook Open Graph meta tags. You can access this data via the page
method.
# app/views/inertia.html.erb
<% content_for(:head) do %>
<meta name="twitter:title" content="<%= page["props"]["event"].title %>">
<% end %>
<div id="app" data-page="<%= page.to_json %>"></div>
Sometimes you may even want to provide data to the root template that will not be sent to your JavaScript page / component. This can be accomplished by passing the view_data
option.
def show
event = Event.find(params[:id])
render inertia: 'Event', props: { event: }, view_data: { meta: event.meta }
end
You can then access this variable like a regular local variable.
# app/views/inertia.html.erb
<% content_for(:head) do %>
<meta
name="description"
content="<%= local_assigns.fetch(:meta, "Default description") %>">
<% end %>
<div id="app" data-page="<%= page.to_json %>"></div>
Rails generators
Inertia Rails provides a number of generators to help you get started with Inertia in your Rails application. You can generate controllers or use scaffolds to create a new resource with Inertia responses.
Scaffold generator
To create a resource with Inertia responses, execute the following command in the terminal:
bin/rails generate inertia:scaffold ModelName field1:type field2:type
Example output:
$ bin/rails generate inertia:scaffold Post title:string body:text
invoke active_record
create db/migrate/20240611123952_create_posts.rb
create app/models/post.rb
invoke test_unit
create test/models/post_test.rb
create test/fixtures/posts.yml
invoke resource_route
route resources :posts
invoke scaffold_controller
create app/controllers/posts_controller.rb
invoke inertia_templates
create app/frontend/pages/Post
create app/frontend/pages/Post/Index.svelte
create app/frontend/pages/Post/Edit.svelte
create app/frontend/pages/Post/Show.svelte
create app/frontend/pages/Post/New.svelte
create app/frontend/pages/Post/Form.svelte
create app/frontend/pages/Post/Post.svelte
invoke resource_route
invoke test_unit
create test/controllers/posts_controller_test.rb
create test/system/posts_test.rb
invoke helper
create app/helpers/posts_helper.rb
invoke test_unit
Tailwind CSS integration
Inertia Rails tries to detect the presence of Tailwind CSS in the application and generate the templates accordingly. If you want to specify templates type, use the --inertia-templates
option:
inertia_templates
- defaultinertia_tw_templates
- Tailwind CSS
Controller generator
To create a controller with an Inertia response, execute the following command in the terminal:
bin/rails generate inertia:controller ControllerName action1 action2
Example output:
$ bin/rails generate inertia:controller pages welcome next_steps
create app/controllers/pages_controller.rb
route get 'pages/welcome'
get 'pages/next_steps'
invoke test_unit
create test/controllers/pages_controller_test.rb
invoke helper
create app/helpers/pages_helper.rb
invoke test_unit
invoke inertia_templates
create app/frontend/pages/Pages
create app/frontend/pages/Pages/Welcome.jsx
create app/frontend/pages/Pages/NextSteps.jsx
Customizing the generator templates
Rails generators allow templates customization. For example, to customize the controller generator view template, create a file lib/templates/inertia_templates/controller/react/view.jsx.tt
:
export default function <%= @action.camelize %>() {
return (
<h1>Hello from my new default template</h1>
);
}
You can find the default templates in the gem's source code:
- Default controller generator templates
- Default scaffold generator templates
- Tailwind controller generator templates
- Tailwind scaffold generator templates
TIP
You can also replace the whole generator with your own implementation. See the Rails documentation for more information.
Maximum response size
To enable client-side history navigation, all Inertia server responses are stored in the browser's history state. However, keep in mind that some browsers impose a size limit on how much data can be saved within the history state.
For example, Firefox has a size limit of 640k characters and throws a NS_ERROR_ILLEGAL_VALUE
error if you exceed this limit. Typically, this is much more data than you'll ever practically need when building applications.