Quick Start

Already using the starter template? Its services, middleware, root template and frontend are configured for you. These steps are for adding Inertia to an existing app or building one manually.

Every app needs the same four things:

1. Register the services

Choose one backend style. All three use the same protocol middleware and the same Render(...) result.

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddValidation();                    // .NET 10 source-generated validation
builder.Services.AddAntiforgery(o => o.HeaderName = InertiaHeaders.XsrfToken);
builder.Services.AddInertia(o =>
{
    o.Share("appName", "Demo");
});

var app = builder.Build();

app.UseStaticFiles();                                // serves wwwroot/build (Vite output)
app.UseInertia();                                    // before the endpoints
app.UseInertiaAntiforgery();                         // XSRF-TOKEN cookie; 419 for unsafe requests without it

app.MapGet("/", () => Render("Home", new InertiaProps
{
    ["greeting"] = "Hello from .NET",
}));

app.Run();

2. Add the root template

The root template is an HTML file in the content root. The default name is app.html.

<!-- app.html -->
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My app</title>
  @viteReactRefresh
  @vite("ClientApp/app.tsx")
  @inertiaHead
</head>
<body>
  @inertia
</body>
</html>

Remove @viteReactRefresh for Vue and Svelte. @inertia is required. The other tokens are described in Pages and responses.

Make sure app.html is copied to the output and publish directory:

<ItemGroup>
  <Content Include="app.html" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

3. Create the page component

The page name passed to Render must match the client resolver. With @inertiajs/vite the resolver maps ClientApp/pages/** automatically.

// ClientApp/pages/Home.tsx
export default function Home({ greeting }: { greeting: string }) {
  return <h1>{greeting}</h1>
}

The client entry only needs to start Inertia:

// ClientApp/app.tsx
import { createInertiaApp } from '@inertiajs/react'

createInertiaApp()

4. Run it

Start Vite and ASP.NET Core in two terminals, from the project directory:

npm run dev      # terminal 1: Vite, writes wwwroot/hot
dotnet watch     # terminal 2: ASP.NET Core, Development environment

Open the URL printed by dotnet watch (not the Vite URL). The first visit to / should display “Hello from .NET”.

For production, build the client and publish the app:

npm run build
dotnet publish -c Release

Deploy wwwroot/build and app.html with the published app.

Where to go next