Server-Side Setup

The first step when installing Inertia is to configure your server-side framework. These docs are written from the perspective of InertiaCore, the ASP.NET Core adapter — AspNetCore.InertiaCore on NuGet. Examples for the Laravel adapter are included as a tab in every code block so you can follow along in either runtime. For other frameworks, see the community adapters.

Scaffold a new InertiaCore app

The fastest way to start a new Inertia project on ASP.NET Core is the create-inertiacore scaffolder, which wires up AspNetCore.InertiaCore, Vite, and your frontend framework of choice (Vue, React, or Svelte) in one step:

npm init inertiacore@latest
# or
npx create-inertiacore@latest

If you’d prefer to add InertiaCore to an existing ASP.NET Core project, follow the manual steps below.

Installation

Install dependencies
Install the InertiaCore server-side adapter. The Vite helper is optional but recommended — it auto-wires Inertia.Version(Vite.GetManifestHash) when your assets change, so you don’t have to.
Terminal window
dotnet add package AspNetCore.InertiaCore
Terminal window
composer require inertiajs/inertia-laravel

Setup root template

Next, create the root view that will be loaded on the first page visit. InertiaCore renders it via @await Inertia.Html(Model) (and optionally @await Inertia.Head(Model) for SSR head fallback). By default the root view lives at ~/Views/App.cshtml; override it through AddInertia(options => options.RootView = ...) if needed.

@using InertiaCore
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1">
        @Vite.Input("src/app.tsx")
        @await Inertia.Head(Model)
    </head>
    <body>
        @await Inertia.Html(Model)
    </body>
</html>

<html>
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1">
        @vite('resources/js/app.js')
        <x-inertia::head />
    </head>
    <body>
        <x-inertia::app />
    </body>
</html>

Inertia.Html(Model) renders a <div> with an id of app as the mounting point for your JavaScript application. You may customize the id by passing a second argument.

@using InertiaCore
<!DOCTYPE html>
<html>
    ...
    <body>
        @await Inertia.Html(Model, "custom-app-id")
    </body>
</html>

If you change the id of the root element, be sure to update it client-side as well.

Inertia.Head(Model) emits SSR head fallback content for managing <title> and <meta> tags when SSR is not active.

Register InertiaCore

Register InertiaCore in Program.cs with AddInertia() and add the middleware with UseInertia(). The Vite helper is optional — include it if you’re bundling assets with Vite.

using InertiaCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddInertia();
builder.Services.AddViteHelper();

var app = builder.Build();

app.UseStaticFiles();
app.UseInertia();
app.MapControllers();

app.Run();

UseInertia() registers the InertiaCore middleware, which handles protocol headers, partial reloads, validation-error forwarding, and asset versioning. Inertia.Version(...) sets your asset version and Inertia.Share(...) defines shared data.

Create your first response

That’s it, you’re all ready to go server-side! Return an Inertia response from a controller with Inertia.Render("Component", props). The component path maps to a JavaScript page under your frontend pages/ directory.

using InertiaCore;

public class EventsController : Controller
{
    private readonly AppDbContext _context;

    public EventsController(AppDbContext context) => _context = context;

    [HttpGet("/events/{id:int}")]
    public IActionResult Show(int id)
    {
        var evt = _context.Events.Find(id);

        return Inertia.Render("Event/Show", new
        {
            Event = new
            {
                evt.Id,
                evt.Title,
                evt.StartDate,
                evt.Description,
            },
        });
    }
}

use Inertia\Inertia;

class EventsController extends Controller
{
    public function show(Event $event)
    {
        return Inertia::render('Event/Show', [
            'event' => $event->only(
                'id',
                'title',
                'start_date',
                'description',
            ),
        ]);
    }
}

Razor Tag Helper

InertiaCore provides a <title inertia> tag helper for managing the document title from the root view. The Laravel adapter’s @inertiaHead / @inertia Blade directives are still supported for legacy projects but the Blade components shown above are recommended for new applications.

@using InertiaCore
<!DOCTYPE html>
<html>
    <head>
        <title inertia>My InertiaCore App</title>
        @Vite.Input("src/app.tsx")
        @await Inertia.Head(Model)
    </head>
    <body>
        @await Inertia.Html(Model)
    </body>
</html>