Inertia.Net

Configuration

InertiaOptions, Vite, SSR, props, state and the middleware and result API.

On this page

Core configuration is passed to AddInertia; error page options use AddInertiaErrorPages. Options marked “Development only” do nothing in other environments.

AddInertia(o => ...): InertiaOptions

OptionDefaultDescription
RootView"app.html"Root template relative to the content root (a Razor view name with UseRazorRootView). Paths outside the content root are refused.
RootElementId"app"Id of the root element and the data-page script.
VersionnullAsset version. null means the Vite manifest hash, or "" without one.
VersionResolvernullFunc<HttpContext, string?> per-request version; wins over Version when non-null.
EncryptHistoryfalseEncrypt browser history state of every page.
WithAllErrorsfalseSend every validation message per field instead of the first.
PreserveBigIntegersfalseEmit integers beyond ±(2^53−1) as {"$bigint":"..."}.
ExposeSharedPropKeystrueList top-level shared keys in sharedProps.
CspNoncenullFunc<HttpContext, string?>: the request's CSP nonce.
ConvertExternalRedirectstrueTurn an Inertia redirect to another origin into 409 + X-Inertia-Location.
UrlResolvernullFunc<HttpContext, string>: the page url.
Pages.Directory / Pages.Extensionsnull / .tsx .jsx .ts .js .vue .svelteDevelopment check that a rendered component has a page file.
TypeScript.OutputPath, .Page<T>(component), .SharedProps<T>(), .FlashData<T>()nullTypeScript declarations, written in Development.
Share(key, value) / Share(key, Func<HttpContext, object?>)noneShared props.

o.Pagination: PaginationOptions

OptionDefaultDescription
DefaultPerPage20Default page size.
MaxPerPage100Maximum page size (below int.MaxValue to allow over-fetching); the default must be between 1 and this value.
PageName"page"Numbered-page query parameter.
PerPageName"perPage"Page-size query parameter.
CursorName"cursor"Cursor query parameter.

o.Vite: ViteOptions

OptionDefaultDescription
PublicDirectory"wwwroot"Web root containing the build directory and hot file.
BuildDirectory"build"Vite output directory under PublicDirectory; also the URL prefix.
ManifestPathnullManifest path relative to the content root. null = {PublicDirectory}/{BuildDirectory}/.vite/manifest.json, then manifest.json.
HotFilePathnullHot file relative to the content root. null = {PublicDirectory}/hot. Read in Development only.
DevServerUrlnullDev server origin, e.g. http://localhost:5173. When set, dev tags always render.
AssetBaseUrlnullReplaces {PathBase}/{BuildDirectory} as the URL prefix of built assets.
PrefetchNoneWaterfall or Aggressive: prefetch code-split chunks after load.
PrefetchConcurrency3Chunks Waterfall downloads at a time.

o.Ssr: SsrOptions

Ssr.ConnectTimeout bounds connection establishment separately from the rendering deadline and defaults to five seconds; use a positive supported duration or Timeout.InfiniteTimeSpan.

OptionDefaultDescription
ModeDisabledDisabled, Preferred or Required. Disabled cannot be overridden per response.
Urlsempty (http://127.0.0.1:13714)SSR server base URLs. Not used with UseNodeProcess().
Timeout5 sTotal deadline per render. Timeout.InfiniteTimeSpan disables it.
MaxResponseBytes16 MiBLimit on actual response bytes, including errors and chunked responses.
MaxPageBytes2 MiBPages whose JSON is larger render on the client without a call.
BundlePathnullSkip SSR while this file is missing, unless the Vite dev server runs.
ExcludePathsemptyRequest paths never rendered on the server (exact, or a trailing * for a prefix).
Concurrency.MaxActive8Renders in flight per server from this app instance; 0 for no limit.
Concurrency.MaxQueued32Renders waiting for a slot per server.
Concurrency.QueueTimeout250 msHow long a render waits for a slot.
CircuitBreaker.EnabledtruePause servers that keep failing.
CircuitBreaker.FailureThreshold5Consecutive failures that open a server's circuit.
CircuitBreaker.BreakDuration10 sHow long an open circuit skips the server before one probe.
Cache.DurationZero (off)Reuse a render for this long when the page JSON is the same.
Cache.StaleForZeroServe stale while re-rendering.
Cache.MaxBytes64 MiBSize of the default store's render cache.
UseNodeProcess(configure?)offStart and supervise Node SSR processes (sets Mode = Preferred when Disabled).

Per response: Render(...).WithSsr(SsrMode) and .WithoutSsr(). The full SSR options are in Server-side rendering.

o.Props: InertiaPropsOptions

OptionDefaultDescription
MaxConcurrency4Loaders marked .Parallel() that run at once per render. Must be positive.

o.State: InertiaStateOptions

OptionDefaultDescription
CookieName".Inertia.State"Cookie name (cookie store) or session key (session store).
RememberPreviousUrlfalseRemember successful page GET URLs for Back() when Referer is unavailable.
PreviousUrlCookieName".Inertia.Previous"Plain previous-URL cookie, with either state store; non-empty and different from CookieName.
CookieSecurePolicySameAsRequestWhen state and previous-URL cookies are Secure.
UseSession()offUse ISession instead of the encrypted cookie.
AddInertiaMvc(o => o.UseTempDataStateStore())offUse MVC TempData. Inertia.Net.Mvc package.

AddInertiaErrorPages(o => ...): InertiaErrorPagesOptions

OptionDefaultDescription
Component"Error"Default error component.
ComponentsemptyPer-status overrides, with keys in StatusCodes.
StatusCodes[403, 404, 500, 503]Non-empty set of statuses from 400–599. Protocol 409 and antiforgery 419 responses are preserved.
EnabledInDevelopmentfalsePreview error components in Development.
PropsnullFunc<HttpContext, int, Exception?, InertiaProps> for additional props.

See Error pages for setup, shared props and existing exception middleware.

Middleware and endpoint API

APIDescription
services.AddInertia(configure?)Registers services and options.
services.AddInertiaErrorPages(configure?) / app.UseInertiaErrorPages(useExceptionHandler: true)Error page services and middleware, before UseInertia(). Use false with your own UseExceptionHandler().
app.UseInertia()The protocol middleware. Before the endpoints; after UseSession() when used.
app.UseInertiaAntiforgery(configure?)Issues the XSRF-TOKEN cookie and validates unsafe requests (419 on failure).
app.MapInertia(pattern, component, props?)GET and HEAD endpoint that renders the component.
services.AddInertiaDevTools(configure?) / app.MapInertiaDevTools()DevTools recorder and read API. A warning is logged when recording is enabled outside Development without an Authorize callback; the read API then returns 404.
app.UseInertiaAntiforgeryCookie(cookieName = "XSRF-TOKEN")Only writes the token cookie; validation is up to you.
endpoint.WithInertiaValidation()Minimal API: validation failures redirect back with errors.
endpoint.WithInertiaPrecognition()Minimal API: WithInertiaValidation() plus Precognition.
healthChecks.AddInertiaSsr(...)SSR health check from the gateway's state.
mvc.AddInertiaMvc(o => o.UseRazorRootView("App"))MVC filter, optional Razor root view and component resolver.
config.ConfigureInertia(configure?)FastEndpoints: validation redirect and Precognition.
Render(component, props?)InertiaResult: .WithStatusCode, .WithRootView, .WithViewData, .WithSsr, .WithoutSsr, .WithSsrCache.
Location(url)InertiaLocationResult.
Back(fallback = "~/")InertiaBackResult: .WithErrors, .WithFlash.
httpContext.Inertia()InertiaFeature: Share, Flash, WithErrors, ClearHistory, EncryptHistory, PreserveFragment.
Send.InertiaAsync(...), Send.InertiaLocationAsync(...), Send.InertiaBackAsync(...)FastEndpoints Send extensions.

Extension points

IInertiaRootView, IInertiaStateStore, ViteAssets, InertiaRequest (parsed headers), InertiaHeaders (header name constants), InertiaSsrException, InertiaSsr.HttpClientName (the SSR HTTP client) and InertiaDiagnostics (meter and activity source names).

Name collisions

The package imports Inertia.Net and static members of Inertia.Net.Inertia when implicit usings are enabled. If a name such as Location collides with a type, use Inertia.Net.Inertia.Location(url). To manage imports yourself, set <InertiaNetImplicitUsings>false</InertiaNetImplicitUsings> in the project and add using Inertia.Net; and using static Inertia.Net.Inertia; where needed.

InertiaPropJsonConverter, InertiaSsrHealthCheck, InertiaCacheEntryKind, InertiaCacheEntryOptions, InertiaPagesOptions, InertiaPrecognition.IsPrecognitive(...) and InertiaPrecognitionMetadata are public APIs for serialization, health checks, cache stores, page checks and precognitive request handling.