Overview & Setup

@stratal/inertia is an Inertia.js v3 server-side adapter for Stratal. It lets you build server-driven single-page applications with React while keeping your routing, controllers, and data logic entirely on the server. There is no client-side router and no API layer to maintain: your Stratal controllers render React pages directly.

Installation

Install the adapter alongside the Inertia.js client libraries, React, and the Vite tooling:

npm install @stratal/inertia @inertiajs/react @inertiajs/vite react react-dom
npm install -D @types/react @types/react-dom vite @cloudflare/vite-plugin

Quick scaffolding

The Inertia CLI generates the recommended directory structure for you:

npx quarry inertia:install

This creates the client entry point, the streaming SSR entry, the root HTML template, a sample page component, and an initial type-definitions file. It also wires InertiaModule.forRoot() (with SSR enabled) into your src/app.module.ts.

The generated layout:

Directorysrc/
- Directoryinertia/
  - app.tsx Client entry
  - ssr.tsx Streaming SSR entry
  - root.html Root HTML template
  - inertia.d.ts Generated page/prop types
  - Directorypages/
    Home.tsx
  - Directorypublic/
    …

Module setup

import { Module } from 'stratal/module'
import { InertiaModule, CookieFlashStore } from '@stratal/inertia'
import rootView from './inertia/root.html?raw'

@Module({
  imports: [
    InertiaModule.forRoot({
      rootView,
      version: '1.0.0',
      ssr: {
        bundle: () => import('./inertia/ssr'),
      },
      flash: {
        store: new CookieFlashStore({ secret: env.FLASH_SECRET }),
      },
      routes: true,
      sharedData: {
        appName: 'My App',
      },
      i18n: {
        only: ['common', 'nav'],
      },
    }),
  ],
})
export class AppModule {}

Configuration options

Option	Type	Description
`rootView`	`string`	Raw HTML template string containing placeholder tags
`version`	`string`	App version string used for cache busting
`ssr`	`InertiaSsrOptions`	Streaming SSR configuration (`bundle`, `disabled`)
`flash`	`InertiaFlashOptions`	Flash message store (`{ store }`)
`sharedData`	`Record<string, unknown>`	Global props shared with every page (static values or `(ctx) => value` resolvers)
`i18n`	`InertiaI18nOptions`	Share backend translations with the frontend (`{ only }`)
`routes`	`boolean`	Inject serialized named routes for client-side URL generation with `useRoute()`
`seo`	`InertiaSeoOptions`	App-wide SEO defaults and title template for backend-driven page metadata
`entryClientPath`	`string`	Path to the client entry file (default: `src/inertia/app.tsx`)

Async configuration

When your Inertia configuration depends on other providers (for example, a config service), use forRootAsync():

import { Module } from 'stratal/module'
import { InertiaModule } from '@stratal/inertia'
import { ConfigService } from './config.service'

@Module({
  imports: [
    InertiaModule.forRootAsync({
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        rootView: config.get('INERTIA_ROOT_VIEW'),
        version: config.get('APP_VERSION'),
        ssr: { bundle: () => import('./inertia/ssr') },
        routes: true,
      }),
    }),
  ],
})
export class AppModule {}

Root HTML template

The rootView option expects a raw HTML string with special placeholder tags. Import src/inertia/root.html with the ?raw suffix so Vite inlines its contents as a string:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    @viteHead
    @inertiaHead
  </head>
  <body>
    @inertia
    @viteScripts
  </body>
</html>

Template placeholders

Placeholder	Description
`@inertia`	Replaced with the serialized page data and the root `#app` element
`@inertiaHead`	Replaced with any `<Head>` tags and SEO metadata for the current page
`@viteHead`	Replaced with Vite CSS and preload links from the build manifest
`@viteScripts`	Replaced with Vite JavaScript `<script>` tags

Next steps

Pages & Rendering Render Inertia pages from your controllers.

Shared Data & Props Share global data and use advanced prop loading strategies.

Server-Side Rendering Stream pages on the server with React 19.

Quarry CLI Explore all available CLI commands including Inertia scaffolding.