Skip to main content

Documentation Index

Fetch the complete documentation index at: https://inertiaserver.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Prerequisites

Any runtime / server that supports standard Reqiest and Response objects, for example:
  • Bun
  • Deno
  • Node.js (v18) - with some configuration
  • Cloudflare Workers - with some configuration

​
1. Install inertia-server

bun add inertia-server

​
2. Create server helpers

On the server, we have to create the inertia helpers. They are used to define pages and parse your requests to handle inertia requests. render function defines how first inertia request is rendered to html. You can use your framework server-side rendering features to render the page, or return a raw html string. Inertia server protocol requires us to provide a div in the markup with data-page attribute that contains the json encoded initial page data.
~/server/inertia.ts
import { createInertia, type InertiaPage } from "inertia-server";
import { renderToString } from "react-dom/server";
import Root from "~/components/root";

export const { definePage, createHelper } = createInertia({
  version: "1.0.0",
  // framework specific component
  render: (page) => renderToString(<Root page={page} />),
  // raw template string
  render: (page) => `
    <html lang="en">
      <head>
        <meta charSet="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Inertia App</title>
      </head>
      <body>
        <div id="app" data-page='${JSON.stringify(page)}' />
      </body>
    </html>
  `,
});

function Root({ page }: { page: InertiaPage }) {
  return (
    <html lang="en">
      <head>
        <meta charSet="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My Inertia App</title>
      </head>
      <body>
        <div id="app" data-page={JSON.stringify(page)} />
      </body>
    </html>
  );
}

​
Step 3: Connect inertia to your server

On each request that works with inertia, you will create a helper that handles all inertia related logic and prepares the correct server response. Any inertia requests that require session features (flashing, errors), require a flash adapter to be provided. Its role is to get and set session flash data for the current request.
app.ts
import { createHelper } from "./inertia";

app.get("/", ({ request }) => {
  const inertia = createHelper({
    request,
    flash: {
      // request.session is your specific session store
      getAll: () => request.session.flash,
      set: (data) => ({
        ...request.session.flash,
        ...data,
      }),
    },
  });

  return inertia.render(page);
});
To make this easier, you can see if we already provide an adapters for your framework.
elysia
import { elysiaAdapter } from "inertia-server/elysia";
import { createHelper } from "./inertia";

app
  .use(
    elysiaAdapter(createHelper, (ctx) => ({
      getAll: () => ctx.session?.flash ?? {},
      set: (data) => {
        ctx.session.flash = data;
      },
    }))
  )
  .get("/", ({ inertia }) => {
    return inertia.render(homePage({ title: "Hello" }));
  });
hono
import { Hono } from "hono";
import { honoAdapter } from "inertia-server/hono";
import { createHelper } from "./inertia";

const app = new Hono();

app.use("*", honoAdapter(createHelper));

app.get("/", (c) => {
  return c.get("inertia").render(homePage({ title: "Hello" }));
});

​
Step 5: Setup inertia on the client

Follow the official documentation for your framework of choice. You will have to setup bundling of your client side code. To make things easier, we have a dedicated bundling integration section in the documentation.

​
Step 6: Create your first page

Define your props on the server:
~/server/inertia.ts
import { prop, type PageProps } from "inertia-server";
import { definePage } from "./inertia";

export const homePage = definePage({
  component: "Home",
  props: {
    title: prop<string>(),
    message: prop<string>(),
  },
});

export type HomePageProps = PageProps<typeof homePage>;
Render your page on the server: 
import { homePage } from "./inertia";

app.get("/", ({ inertia }) => {
  return inertia.render(homePage({ title: "Hello" }));
});
And add your client component:
~/ui/homepage.tsx
import type { HomePageProps } from "~/server/inertia";

export default function Home({ title, message }: HomePageProps) {
  return (
    <div>
      <h1>{title}</h1>
      <p>{message}</p>
    </div>
  );
}

​
Next Steps

Congratulations on setting up inertia! Now you can start building your application.