DOCSEARCHbyAlgolia
Submit Docs

Inertia Rails Documentation

website·Indexed 33 days ago

https://inertia-rails.dev

Documentation for the Inertia.js Rails adapter, enabling the creation of single-page apps using classic server-side routing and controllers. Covers server-side configuration, client-side setup for Vue, React, and Svelte, and advanced features like deferred props, cached props, infinite scroll, and server-side validation.

Tokens
58.8K
Snippets
361
Records
421
Agent score
68%

What's inside Inertia Rails

  1. Overview of Inertia application testing strategies

    Depending on the goal, there are three primary ways to test an Inertia application:

    1. End-to-end (E2E) Tests: Use browser automation tools like Cypress or Capybara. These test the application at the user layer, executing actual JavaScript in the browser. They provide high confidence but are slower.
    2. Client-Side Unit Tests: Use frameworks like Vitest, Jest, or Mocha to test JavaScript page components in isolation using Node.js.
    3. Endpoint Tests: Use Inertia Rails' provided test helpers for RSpec or Minitest to verify server-side responses, props, and components.

  2. Overview of Inertia.js for Ruby on Rails

    Inertia.js is a tool that allows developers to build fully client-side rendered single-page apps (SPAs) using classic server-driven patterns. It acts as 'glue' between a server-side framework (like Ruby on Rails) and a client-side framework (such as React, Vue, or Svelte). Unlike traditional SPAs, Inertia does not require a client-side router or a dedicated API; instead, it leverages standard server-side controllers and page views to deliver a seamless SPA experience.

  3. Overview of Server-Side Rendering (SSR) in Inertia Rails

    Server-side rendering (SSR) pre-renders JavaScript pages into HTML on the server. This improves initial load times and enhances search engine indexing. SSR requires Node.js 22 or higher to be installed on the server to run the rendering process in the background.

  4. Overview of Inertia Modal

    Inertia Modal is a library that allows any Inertia page to be rendered as a modal dialog. It supports React and Vue, providing features such as nested/stacked modals, slideovers, headless mode, prefetch support, and native HTML dialog accessibility. Svelte is not supported.

  5. Understand default scroll behavior in Inertia

    By default, Inertia mimics standard browser behavior: when navigating between pages, it automatically resets the scroll position of the document body (and any defined scroll regions) to the top. Additionally, Inertia tracks the scroll position of each page to automatically restore it when the user navigates forward or backward in their browser history.

  6. Route directly to components using shorthand routes

    For pages that do not require a controller method (e.g., static pages like 'About' or 'FAQ'), you can use the inertia method in config/routes.rb to map URLs directly to Inertia components. You can map single pages, multiple pages, use symbols to infer component names, or nest them within namespaces and resource definitions. Since version 3.22.0, you can also pass static props directly within the route definition.
    # In config/routes.rb
Rails.application.routes.draw do
  # Basic usage - maps 'dashboard' URL to 'Dashboard' component
  inertia 'dashboard' => 'Dashboard'

  # Multiple pages at once
  inertia 'about' => 'About', 'contact' => 'Contact'

  # Using a symbol - infers component name from route
  inertia :settings

  # Within namespaces and scopes
  namespace :admin do
    inertia 'dashboard' => 'Admin/Dashboard'
  end

  # Within resource definitions
  resources :users do
    inertia :activity, on: :member
    inertia :statistics, on: :collection
  end

  # Passing static props (Available since rails=3.22.0)
  inertia 'about' => 'About', props: { title: 'About us' }
end

  7. Understand the Inertia.js architecture

    Inertia.js allows developers to build applications using a server-side framework (like Rails or Laravel) for routing, controllers, middleware, authentication, and data fetching, while replacing the traditional server-side view layer (e.g., Ruby or PHP templates) with JavaScript page components. This enables the use of frontend frameworks like React, Vue, or Svelte without abandoning the productivity of a server-side framework.

  8. Understand the Inertia.js development paradigm

    Inertia.js allows developers to build modern single-page applications (SPAs) using a classic server-side rendered workflow. Instead of building a separate REST or GraphQL API with its own authentication, state management, and deployment strategy, developers continue to use server-side controllers and ORMs to fetch data. The key difference is that Inertia renders JavaScript page components (React, Vue, or Svelte) instead of traditional server-side HTML views, providing a client-side application experience without the overhead of an API layer.

  9. Handle server-side errors in Inertia development

    In development, Inertia automatically intercepts non-Inertia responses (such as server-side exceptions) and displays them in a modal. This allows developers to see detailed error reporting without manually checking the browser's network tab. If your application uses a Content Security Policy (CSP) that restricts inline styles, you can pass a nonce to createInertiaApp() to permit the styles used by the error modal.

  10. Define routes for Inertia-Rails

    In Inertia, all application routes are defined server-side in Rails. This eliminates the need for client-side routing libraries like Vue Router or React Router. You define standard Rails routes and return Inertia responses from the corresponding controller actions.

  11. Understand automatic CSRF protection in Inertia Rails

    Inertia's Rails adapter automatically includes the proper CSRF token when making requests via Inertia or Axios, requiring no additional configuration for standard use cases. The HTTP client automatically detects the XSRF-TOKEN cookie and includes it in the X-XSRF-TOKEN header for every request. By default, the Rails adapter refreshes this cookie on every protected request.

  12. Prevent privileged data exposure with History Encryption

    Inertia.js provides history encryption to prevent users from accessing privileged information stored in the window's history state (e.g., after logging out). It uses the browser's crypto API to encrypt page data before pushing it to the history state, storing the key in session storage. This feature requires a secure environment (SSL enabled) as it relies on window.crypto.subtle.