Configuration
ts
import * as assets from 'virtual:hono-inertia/assets';
inertia({
// The Vite plugin's virtual module. Gives the asset version, the asset tags
// of the built-in template, and the plugin's SSR entry.
assets,
// Optional. Options for the built-in template (see Root template below)
template: { lang: 'en', title: 'My app' },
// Optional. Your own HTML instead of the built-in template. Receives the
// page object, view data, the SSR result (undefined without SSR), and the
// Hono context. See Root template below.
render: (page, viewData, ssr, c) => html,
// Optional. Asset version, as a string or a sync/async function. Defaults
// to assets.version. Without either, version checks are off.
version,
// Global shared props, merged into every response
share: (c) => ({
auth: { user: getUser(c) },
}),
// Optional. The page.url sent to the client. Defaults to the request's path
// and query. See Page URL below.
resolveUrl: (c) => c.req.url,
// Optional. Defaults to rendering with assets.ssr when the plugin has an
// SSR entry. Posts the page object to an Inertia SSR server, or pass
// { render } to render in the same process. enabled takes a function of
// the context to turn SSR off for some requests.
ssr: {
url: 'http://127.0.0.1:13714',
enabled: (c) => !c.req.path.startsWith('/admin'),
},
// Called when SSR fails and the page falls back to client-side rendering.
// Defaults to console.error. Throw from it to fail the request instead.
onSsrError: (error, page) =>
logger.error({ error, component: page.component }),
// Cache-Control for responses the adapter emits (see Caching under Security).
// Defaults to 'private, no-cache, must-revalidate'. Set false to omit it.
cacheControl: 'private, no-cache, must-revalidate',
// Called when a deferred(fn).rescue() prop throws (see deferred under Prop types).
// Defaults to console.error.
onRescue: (error, prop) => logger.error({ error, prop }),
// Optional. Keeps validation errors and flash data for the page after a
// redirect in a signed cookie, or in a store you pass (see Sessions below)
session: { secret: env.SESSION_SECRET },
// Optional. Pages get every message per field as an array, instead of the
// first one (see Validation below)
allErrors: true,
// Optional. Maps the name render() takes to the component name the client
// resolves
transformComponent: (name) => `Pages/${name}`,
// Optional. Prefix and path of the short-lived cookies that carry
// clearHistory() and preserveFragment() across redirects. Defaults to
// 'inertia_' and '/'.
flagCookies: { prefix: 'inertia_', path: '/' },
});Root template
Without a render option, inertia() renders the first visit's HTML itself:
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>
<!-- The page's asset tags, the SSR head, then template.head -->
</head>
<body>
<script data-page="app" type="application/json">
{"component":"Home",...}
</script>
<div id="app"></div>
</body>
</html>With SSR, the body is the SSR body instead, and the <title> is left out when the SSR head has one. The asset tags come from assets.assetTagsFor(page.component), so the page's own chunks load with the entry (see Preloading the page). They come before the SSR head, so the browser starts fetching them first.
template takes these options:
langsets<html lang>. Pass a string, or a function of the page and the context for a language resolved per request. A function that returnsundefinedleaves it out.htmlAttributesis a function of the page and the context that returns more attributes for<html>, such asdata-theme. The adapter escapes the values and leaves out the ones that areundefined.titleis a<title>for pages whose SSR head has none.headis HTML for<head>, such as a favicon or fonts. Pass a string, or a function of the page, the context,render()'s view data and the SSR result. With the context it can read a CSP nonce, and with the SSR result it can add meta tags only when SSR rendered none.idis the root element's id, whichcreateInertiaApp()reads. It defaults toapp.
ts
inertia({
assets,
template: {
lang: (page) => String(page.props.locale ?? 'en'),
htmlAttributes: (page, c) => ({
'data-mode': getCookie(c, 'mode') === 'dark' ? 'dark' : undefined,
}),
head: (page, c, viewData, ssr) =>
ssr?.head || typeof viewData.robots !== 'string'
? ''
: `<meta name="robots" content="${escapeHtml(viewData.robots)}">`,
},
});For other HTML, pass render. Embed the page with serializePage(page), never a bare JSON.stringify (see Security):
ts
import { inertia, serializePage } from '@brachkow/hono-inertia';
import { assetTagsFor } from 'virtual:hono-inertia/assets';
inertia({
assets,
render: (page, viewData, ssr) =>
ssr
? `<!DOCTYPE html><html><head>${ssr.head}${assetTagsFor(page.component)}</head><body>${ssr.body}</body></html>`
: `<!DOCTYPE html><html><head>${assetTagsFor(page.component)}</head><body><script data-page="app" type="application/json">${serializePage(page)}</script><div id="app"></div></body></html>`,
});