Installation

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

pnpm add inertia-server

yarn add inertia-server

npm install 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.

Learn about page definitions
See our ecosystem integrations

Getting Started

Concepts

Configuration

Integrations

Prerequisites

1. Install `inertia-server`

2. Create server helpers

Step 3: Connect inertia to your server

Step 5: Setup inertia on the client

Step 6: Create your first page

Next Steps

​Prerequisites

​1. Install inertia-server

​2. Create server helpers

​Step 3: Connect inertia to your server

​Step 5: Setup inertia on the client

​Step 6: Create your first page

​Next Steps

Prerequisites

1. Install `inertia-server`

2. Create server helpers

Step 3: Connect inertia to your server

Step 5: Setup inertia on the client

Step 6: Create your first page

Next Steps