Inertia.js — Build Single-Page Apps Without a Separate API

Introduction

Inertia.js is a routing library that bridges server-side frameworks (Laravel, Rails, Django) and client-side frameworks (React, Vue, Svelte) without requiring a REST or GraphQL API. The server returns page components and props as JSON; the client swaps components and updates the URL, creating a single-page app experience powered by traditional server-side routing and controllers.

What Inertia.js Does

• Replaces full page reloads with XHR-based page component swaps for SPA-like navigation
• Lets server-side controllers return page component names and props directly, no API layer needed
• Handles browser history, scroll position, and back/forward navigation automatically
• Supports shared data (auth user, flash messages) across all pages via middleware
• Provides partial reloads to refresh only specific props without reloading the full page dataset

Architecture Overview

Inertia works as a protocol between a server-side adapter and a client-side adapter. On the first request, the server renders a full HTML page containing a root <div> with the initial page component and props encoded as a data attribute. On subsequent navigation, the client intercepts link clicks, sends an XHR request with an X-Inertia header, and the server responds with a JSON payload containing the component name, props, and URL. The client-side adapter (React, Vue, or Svelte) swaps the page component without a full reload.

Self-Hosting & Configuration

• Install the server-side adapter for your framework (Laravel, Rails, or Django) via the respective package manager
• Install the client-side adapter (@inertiajs/react, @inertiajs/vue3, or @inertiajs/svelte) via npm
• Configure the root Blade/ERB/Jinja template to include the Inertia app entry point
• Use the Inertia middleware to share global data like authentication state and flash messages
• Enable SSR by running the Inertia SSR server alongside your application server

Key Features

• No API layer: controllers pass data directly to frontend components as props
• Works with existing server-side routing, middleware, validation, and authentication
• Automatic handling of browser history, scroll preservation, and loading states
• Partial reloads allow refreshing individual props without re-fetching the entire page dataset
• Server-side rendering (SSR) support for improved initial load performance and SEO

Comparison with Similar Tools

• Livewire — sends HTML fragments over the wire for Laravel; Inertia sends JSON props to a full JS frontend framework
• HTMX — returns HTML partials for progressive enhancement; Inertia replaces the entire page component using React/Vue/Svelte
• Next.js / Nuxt — full-stack JS frameworks with their own routing and data fetching; Inertia keeps the backend in PHP/Ruby/Python
• Turbo (Hotwire) — HTML-over-the-wire approach from Rails; Inertia offers richer client-side interactivity via JS frameworks

FAQ

Q: Which server-side frameworks are supported? A: Official adapters exist for Laravel (PHP) and Rails (Ruby). Community adapters are available for Django, Phoenix, Spring Boot, and others.

Q: Do I still need to build an API? A: No, that is the core value proposition. Your controllers return Inertia responses directly to the frontend components.

Q: Does Inertia support server-side rendering? A: Yes, Inertia provides an SSR package that pre-renders pages on the server using a Node.js process alongside your application.

Q: Can I use Inertia with TypeScript? A: Yes, the React, Vue, and Svelte adapters ship TypeScript definitions and support typed page props.

Sources

• https://github.com/inertiajs/inertia
• https://inertiajs.com/