# Inertia `@arkstack/inertia` is a runtime-agnostic [InertiaJS](https://inertiajs.com) server adapter. It lets you build a single-page app, Vue, React, or Svelte without an API: your controllers return page components and props, and Inertia handles the client-side routing. It works with both the Express and H3 drivers and serves responses through the same `@arkstack/http` `Response` the rest of the framework uses, so there is no special send path to wire up. ## Install ```sh pnpm add @arkstack/inertia ``` `@arkstack/http` and `@arkstack/view` are peer dependencies (apps already have `@arkstack/http`; `@arkstack/view` is only needed to render the root template). On the client, install the Inertia adapter for your framework — `@inertiajs/vue3`, `@inertiajs/react`, or `@inertiajs/svelte`; see **Set up the client** under Setup below. ## How it works On the first visit Arkstack returns a full HTML document with the page object embedded in a `data-page` attribute. The Inertia client boots from it and, on every subsequent visit, sends an XHR with an `X-Inertia` header; the adapter replies with a JSON page object instead of HTML and the client swaps the page without doing a full reload. ```json { "component": "Users/Index", "props": { ... }, "url": "/users", "version": "" } ``` ## Setup ### 1. Register the middleware Add the `inertia()` middleware to `src/config/middleware.ts` so the adapter can read the request and bind its context. Register it under `before` (alongside `resora()`) so the context is bound before your route handlers run. ::: code-group ```ts [Express] // src/config/middleware.ts import { inertia, resora } from '@arkstack/driver-express/middlewares' import { MiddlewareConfig } from '@arkstack/driver-express/types' export default (): MiddlewareConfig => { return { before: [resora(), inertia()], } } ``` ```ts [H3] // src/config/middleware.ts import { inertia, resora } from '@arkstack/driver-h3/middlewares' import { MiddlewareConfig } from '@arkstack/driver-h3/types' export default (): MiddlewareConfig => { return { before: [resora(), inertia()], } } ``` ```ts [Fastify] // src/config/middleware.ts import { inertia, resora } from '@arkstack/driver-fastify/middlewares' import { MiddlewareConfig } from '@arkstack/driver-fastify/types' export default (): MiddlewareConfig => { return { before: [resora(), inertia()], } } ``` ::: ### 2. Publish the config and root template ```sh ark publish --package @arkstack/inertia ``` This writes `src/config/inertia.ts` and a root Edge template to `src/resources/views/app.edge`. The template uses three Edge tags the adapter registers for you: - `@inertiaHead` — SSR head tags (empty without SSR). - `@vite(...)` — your client bundle (dev-server tags in development, hashed manifest assets in production); see **Set up the client** below. - `@inertia` — the mount element the client hydrates. ```edge @inertiaHead @vite('resources/js/app.ts') @inertia ``` ### 3. Set up the client The front-end is a standard [Vite](https://vitejs.dev) project. Keep your client code **outside `src/`** (the build only compiles `src/**/*.ts` for Node) — `resources/js/` is a good home. Install Vite, the Inertia client adapter, and the framework plugin: ::: code-group ```sh [Vue] pnpm add vue @inertiajs/vue3 pnpm add -D vite @vitejs/plugin-vue ``` ```sh [React] pnpm add react react-dom @inertiajs/react pnpm add -D vite @vitejs/plugin-react ``` ```sh [Svelte] pnpm add svelte @inertiajs/svelte pnpm add -D vite @sveltejs/vite-plugin-svelte ``` ::: Add a `vite.config.ts`. Build into `public/build` (the framework serves `public/`), list every entry you reference from `@vite(...)` as an input so each lands in the manifest, and set `publicDir: false` so Vite doesn't try to copy `public/` into itself: ::: code-group ```ts [Vue] import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' export default defineConfig({ plugins: [vue()], publicDir: false, build: { manifest: true, outDir: 'public/build', rolldownOptions: { input: ['resources/css/app.css', 'resources/js/app.ts'], }, }, }) ``` ```ts [React] import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], publicDir: false, build: { manifest: true, outDir: 'public/build', rolldownOptions: { input: ['resources/css/app.css', 'resources/js/app.tsx'], }, }, }) ``` ```ts [Svelte] import { defineConfig } from 'vite' import { svelte } from '@sveltejs/vite-plugin-svelte' export default defineConfig({ plugins: [svelte()], publicDir: false, build: { manifest: true, outDir: 'public/build', rolldownOptions: { input: ['resources/css/app.css', 'resources/js/app.ts'], }, }, }) ``` ::: The published root template loads your bundle with the `@vite` tag, which **handles both modes for you**. Vite dev-server tags in development, and the hashed manifest assets in production: ```edge @inertiaHead @vite(['resources/js/app.ts', 'resources/css/app.css']) ``` Every path passed to `@vite(...)` must be a Vite build input (see the configs above) so it resolves from the manifest in production. Override the dev server URL with `VITE_DEV_URL`; in production the manifest is read from `public/build/.vite/manifest.json`, and the build assets are served from `public/build`. Run `vite build` (e.g. `pnpm build:client`) before deploying. **React only:** `@vitejs/plugin-react` needs the React Refresh preamble injected before your entry loads. Add `@viteReactRefresh` immediately above `@vite` in the root template, otherwise React throws "can't detect preamble" in development (the tag emits nothing in production). The `inertia-react` publish target adds it for you. ```edge @inertiaHead @viteReactRefresh @vite('resources/js/app.tsx') ``` Create the client entry that boots Inertia and resolves your pages from `resources/js/Pages`: ::: code-group ```ts [Vue] // resources/js/app.ts import { createApp, h } from 'vue' import { createInertiaApp } from '@inertiajs/vue3' createInertiaApp({ resolve: (name) => { const pages = import.meta.glob('./Pages/**/*.vue', { eager: true }) return pages[`./Pages/${name}.vue`] }, setup({ el, App, props, plugin }) { createApp({ render: () => h(App, props) }) .use(plugin) .mount(el) }, }) ``` ```tsx [React] // resources/js/app.tsx import { createInertiaApp } from '@inertiajs/react' import { createRoot } from 'react-dom/client' createInertiaApp({ resolve: (name) => { const pages = import.meta.glob('./Pages/**/*.tsx', { eager: true }) return pages[`./Pages/${name}.tsx`] }, setup({ el, App, props }) { createRoot(el).render() }, }) ``` ```ts [Svelte] // resources/js/app.ts import { createInertiaApp } from '@inertiajs/svelte' import { mount } from 'svelte' createInertiaApp({ resolve: (name) => { const pages = import.meta.glob('./Pages/**/*.svelte', { eager: true }) return pages[`./Pages/${name}.svelte`] }, setup({ el, App, props }) { mount(App, { target: el, props }) }, }) ``` ::: Run Vite alongside `ark dev` during development (e.g. `vite`), and `vite build` for production. ## Rendering pages Return `inertia(component, props)` (or `Inertia.render(...)`) from a controller. The same call produces an HTML document on the first visit and a JSON page object on Inertia visits. ```ts import { inertia } from '@arkstack/inertia' import { User } from '@app/models/User' export class UserController { async index() { return inertia('Users/Index', { users: await User.all(), }) } } ``` `props` may be plain JSON-serializable values, synchronous or asynchronous callbacks (resolved lazily, including when nested), or one of the prop wrappers below. ## Shared data Share props with every response globally at boot, or per request inside a handler: ```ts import { inertia } from '@arkstack/inertia' // At boot — applies to every request inertia().share('appName', config('app.name')) // Inside a request — scoped to this request only inertia().share({ flash: session.get('flash') }) ``` Page props override shared props of the same name. ## Partial reloads Inertia can re-fetch a subset of props for the current component. The adapter honours the `only`/`except` filters automatically; you control which props participate using the prop wrappers: | Helper | Initial load | Partial reload | | ------------------------------------- | ------------------------ | ------------------------------------ | | plain value / callback | included | included unless filtered out | | `Inertia.always(value)` | included | **always** included, ignores filters | | `Inertia.lazy(fn)` (alias `optional`) | **excluded** | included only when requested | | `Inertia.defer(fn, group?)` | **excluded**, advertised | fetched by the client after load | ```ts return inertia('Users/Index', { // always evaluated users: await User.all(), // only evaluated on a partial reload that asks for `stats` stats: Inertia.lazy(() => expensiveStats()), // excluded from the first response, fetched automatically afterwards chart: Inertia.defer(() => buildChart()), // always present, even on partial reloads auth: Inertia.always({ user: request.user }), }) ``` ## Redirects Use `Inertia.redirect()` / `Inertia.back()` for Inertia-aware redirects. After a `PUT`, `PATCH`, or `DELETE` the status is automatically upgraded to `303 See Other`, which the Inertia client requires to follow the redirect with a `GET`: ```ts async update () { await user.save(); return Inertia.redirect('/users'); // 303 for PUT/PATCH/DELETE, 302 otherwise } ``` To redirect to an external URL (or force a full page visit), use `Inertia.location(url)`. On an Inertia visit it responds `409` with an `X-Inertia-Location` header so the client performs a hard navigation. ## Asset versioning Set `version` in `src/config/inertia.ts` to a build hash (a string or a function returning one). When the client reports a different version on a `GET` visit, the adapter responds `409` with `X-Inertia-Location` and the client reloads to pick up fresh assets. Leave it `null` to disable versioning. ```ts // src/config/inertia.ts export default (): InertiaConfig => { return { root_view: 'app', version: env('INERTIA_VERSION', null), ssr: { enabled: false }, } } ``` You can also set it at runtime: `Inertia.version(() => buildHash())`. ## Configuration | Key | Default | Description | | ------------- | ------------------------------- | -------------------------------------------------------------------------------------- | | `root_view` | `app` | Edge template wrapping the SPA. Falls back to a minimal built-in document when absent. | | `root_id` | `app` | Id of the DOM element the client mounts onto (carries `data-page`). | | `version` | `null` | Asset version string, a resolver function, or `null` to disable. | | `ssr.enabled` | `false` | Render the initial page on a Node SSR server. | | `ssr.url` | `http://127.0.0.1:13714/render` | The SSR server's render endpoint. | | `ssr.bundle` | `dist-ssr/ssr.js` | Path to the built SSR bundle run by `ark inertia:ssr`. | You can also override config at runtime with `Inertia.configure({ ... })` — handy for programmatic setups and tests. ## Server-side rendering With SSR enabled, the **initial** visit is rendered by a separate Node process (your app's SSR bundle) and the resulting markup + head tags are embedded in the response, so crawlers and the first paint get fully rendered HTML. The client then hydrates that markup. Subsequent Inertia visits are unchanged (client-side). If the SSR server is unreachable, the adapter falls back to client-side rendering rather than failing the request. ### 1. Add an SSR entry Create a server entry (`resources/js/ssr.ts`) that renders a page to `{ head, body }` and starts the SSR server: ::: code-group ```ts [Vue] // resources/js/ssr.ts import { createInertiaApp } from '@inertiajs/vue3' import createServer from '@inertiajs/vue3/server' import { renderToString } from '@vue/server-renderer' import { createSSRApp, h } from 'vue' createServer((page) => createInertiaApp({ page, render: renderToString, resolve: (name) => { const pages = import.meta.glob('./Pages/**/*.vue', { eager: true }) return pages[`./Pages/${name}.vue`] }, setup({ App, props, plugin }) { return createSSRApp({ render: () => h(App, props) }).use(plugin) }, }), ) ``` ```tsx [React] // resources/js/ssr.tsx import { createInertiaApp } from '@inertiajs/react' import createServer from '@inertiajs/react/server' import ReactDOMServer from 'react-dom/server' createServer((page) => createInertiaApp({ page, render: ReactDOMServer.renderToString, resolve: (name) => { const pages = import.meta.glob('./Pages/**/*.tsx', { eager: true }) return pages[`./Pages/${name}.tsx`] }, setup: ({ App, props }) => , }), ) ``` ```ts [Svelte] // resources/js/ssr.ts import { createInertiaApp } from '@inertiajs/svelte' import createServer from '@inertiajs/svelte/server' createServer((page) => createInertiaApp({ page, resolve: (name) => { const pages = import.meta.glob('./Pages/**/*.svelte', { eager: true }) return pages[`./Pages/${name}.svelte`] }, setup: ({ App, props }) => App.render(props), }), ) ``` ::: On the client, hydrate the server-rendered markup instead of mounting fresh: Vue uses `createSSRApp`, React uses `hydrateRoot`, and Svelte uses `hydrate`. ### 2. Build and run the SSR server Build the SSR bundle (for example with Vite: `vite build --ssr resources/js/ssr.ts --outDir dist-ssr`), then run it alongside your app with the `inertia:ssr` command, which supervises the process and restarts it if it crashes: ```sh ark inertia:ssr ``` It runs `ssr.bundle` (default `dist-ssr/ssr.js`); override with `--bundle `, or pass `--no-restart` to exit instead of restarting. You can also run the bundle directly with `node dist-ssr/ssr.js`. ### 3. Enable SSR Set `ssr.enabled` in `src/config/inertia.ts` (or `INERTIA_SSR=true`). Point `ssr.url` at the SSR server if it isn't on the default port. ```ts ssr: { enabled: env('INERTIA_SSR', false), url: env('INERTIA_SSR_URL', 'http://127.0.0.1:13714/render'), } ```