Asset versioning
Every Inertia response carries page.version. When a client's X-Inertia-Version header no longer matches the server's version, the adapter answers a GET with 409 and X-Inertia-Location, and the client performs a full page visit, which loads the new HTML and asset URLs. This keeps a tab that stayed open across a deploy from requesting content-hashed chunks that no longer exist.
The 409 also carries the new version in X-Inertia-Version. The client uses it to tell a deploy-driven reload from a plain location() redirect. It fires a cancelable inertia:location event with versionChange: true. For background async visits (polling, prefetching, deferred props) it skips the forced reload, so the next visit the user starts picks up the new assets without interrupting them.
Vite plugin
honoInertia() connects the server to the client build. It gives the server the version and the HTML tags that load the client:
// vite.config.ts
import { honoInertia } from '@brachkow/hono-inertia/vite-plugin';
export default defineConfig({
plugins: [vue(), inertia(), honoInertia({ entry: 'src/client.ts' })],
});// server.ts
import * as assets from 'virtual:hono-inertia/assets';
app.use(inertia({ assets }));The module exports version, assetTags, assetTagsFor(), manifest and ssr. A custom render can import them by name.
Add /// <reference types="@brachkow/hono-inertia/vite-plugin/client" /> to a .d.ts file in your project to type the virtual:hono-inertia/assets import.
- In production,
assetTagsholds the client entry's script,modulepreloadlinks for the chunks it imports, and the stylesheets of all of them. Withbuild.cssCodeSplit: false, it links the single CSS file Vite writes instead. Every tag carriescrossorigin, as in Vite's own HTML output. URLs follow Vite'sbase.versionis the same hashmanifestVersioncomputes (see below). - Under
vite dev,assetTagsis whatever Vite's own HTML transform adds, such as/@vite/clientand the React Refresh preamble, followed by the entry script.versionis'dev'. - The plugin turns on the client build's manifest and sets the entry as its input, unless you set either yourself. Once the client build is written, the plugin moves the manifest to
node_modules/.hono-inertia/. The manifest lists every page and source path, and static hosts such as Workers would otherwise serve it to anyone. The server build reads it from there. - In an app build (
builderin the Vite config, as Cloudflare's plugin sets), the plugin builds the client before the other environments, because they inline its asset tags. In separatevite buildruns, build the client first. - Pass
versionSaltto change the version without a client change, as with the salt argument below. - Pass
pagesto generate the types for typed page props. - Pass
ssrwith the SSR entry's path, and the module exports its default export asssr, whichinertia({ assets })renders with (see SSR). Without it,ssrisnull. manifestis the parsed client manifest, for building your own tags. It isnullundervite dev.
Vite 7 or newer is required.
Preloading the page
A page component that the client loads with import.meta.glob starts downloading only after the entry ran and Inertia picked the component. assetTagsFor(page.component) returns assetTags plus the stylesheets and modulepreload links of that page and the chunks it imports, so the browser fetches them together with the entry. The built-in template uses it, and a custom render can too:
import { assetTagsFor } from 'virtual:hono-inertia/assets';
render: (page) =>
`<!DOCTYPE html><html><head>${assetTagsFor(page.component)}</head><body>...</body></html>`,It leaves out what the entry already loads. With the pages option, the plugin knows which file each page name stands for. Without it, pass pageSource with [name] in place of the page name, or a list of patterns for several extensions:
honoInertia({ entry: 'src/client.ts', pageSource: 'src/pages/[name].vue' });[name] can appear more than once, and every copy has to match the same name. 'src/views/[name]/[name].vue' finds Landing in src/views/Landing/Landing.vue.
For a page the plugin does not know, and under vite dev, assetTagsFor() returns assetTags.
Without the plugin
Derive the version from your Vite manifest with manifestVersion:
import manifest from './dist/client/.vite/manifest.json';
import { inertia } from '@brachkow/hono-inertia';
import { manifestVersion } from '@brachkow/hono-inertia/vite';
app.use(inertia({ version: manifestVersion(manifest), render }));- It hashes the sorted emitted filenames (sha256, 16 hex chars), not the manifest JSON. Vite already puts content hashes in filenames, so the version changes exactly when an open tab's chunk URLs stop working. A server-only deploy does not force-reload every open tab, as a commit SHA or deployment ID would. Reordered manifest keys or changed metadata don't change the version.
manifestVersioncomputes the hash once per isolate and memoizes it. It doesn't touch the file system and uses only WebCrypto, so it works on Workers, Deno, Bun, and Node.- Pass a salt as the second argument,
manifestVersion(manifest, salt), and change it to force a global reload after a server-only change that breaks the prop contract with old bundles. vite devproduces no manifest, so use a constant in development, for exampleversion: import.meta.env.PROD ? manifestVersion(manifest) : 'dev'.
Whatever you use as a version, keep it short. The client sends it back verbatim in the X-Inertia-Version request header on every visit, and proxies reject requests with headers over about 8 to 16 KB (Cloudflare: 16 KB). Never use the manifest contents themselves.
Omitting version disables the check (page.version is null). A missing or empty client header never triggers a 409 either.
Recovering from dead chunks (vite:preloadError)
The 409 mechanism covers chunks loaded through an Inertia GET. It can't cover dynamic imports unrelated to a visit (import('some-lib') on a button click), or a deploy that lands after the version check passed but before the import() ran. For those cases, add a vite:preloadError listener in the app that navigates once. Vite dispatches this event for failing dynamic imports, not only for preload links:
import { router } from '@inertiajs/vue3'; // or react / svelte
let pendingUrl: string | null = null;
router.on('start', (event) => {
pendingUrl = event.detail.visit.url.href;
});
const RELOADED_AT = 'inertia:chunk-reload';
const COOLDOWN_MS = 10_000;
const sessionStorageUsable = () => {
try {
window.sessionStorage.getItem(RELOADED_AT);
return true;
} catch {
return false;
}
};
window.addEventListener('vite:preloadError', (event) => {
if (!sessionStorageUsable()) return;
const last = Number(sessionStorage.getItem(RELOADED_AT) ?? 0);
if (Date.now() - last < COOLDOWN_MS) return;
sessionStorage.setItem(RELOADED_AT, String(Date.now()));
event.preventDefault();
window.location.assign(pendingUrl ?? window.location.href);
});Four details matter:
- Navigate to the target URL, not the current one. Inertia resolves the page component before it pushes history state, so when the chunk fails, the address bar still shows the old page. A bare
location.reload()re-renders the page the user was already on, and the click appears to do nothing. Take the pending URL fromrouter.on('start'). - Persist the cooldown timestamp instead of using an in-memory flag or one cleared on boot. The reload loop happens across documents, and the entry chunk always boots (only the view chunk returns 404), so any flag reset on boot lets the loop run forever.
- Use
sessionStorage, notlocalStorage. Staleness belongs to one tab's document. WithlocalStorage, one tab's reload would suppress a reload another tab needs. Accessingwindow.sessionStoragethrows in blocked or partitioned storage contexts, so probe it and fail closed by letting the error surface instead of looping. - Call
preventDefault()only on the path that navigates. Otherwise the import resolves toundefinedand the caller throws aTypeErroranyway.