Inertia Static Laravel Package

Getting Started

This package gives your Inertia front end a generated, static view of your Laravel routes so client-side navigation and route helpers work without a server round-trip. The workflow is: Laravel generates a JSON manifest → your JS imports it → the Vite plugin keeps it in sync during builds.

1. Install the package (composer require) and register the Vite plugin in vite.config.ts alongside laravel-vite-plugin.
2. Add the generated manifest to .gitignore — resources/js/inertia-static.json is a build artifact, not source.
3. Generate it once locally: php artisan inertia-static:manifest.
4. Verify setup: php artisan inertia-static:doctor (new in v0.4.0) — it warns when the manifest is not ignored.
5. Start with vite dev and confirm the plugin resolves routes.

First real use case: a dashboard shell where links, form actions, and route-style helpers are read from the manifest — the front end never needs a JSON endpoint to know your route table.

Where to look first: the doctor command. It is the fastest way to confirm the manifest path, its ignore status, and that the generator is wired up correctly before you involve a CI pipeline.

Implementation Patterns

Generate in CI, never commit. The canonical pipeline order is:

composer install
php artisan inertia-static:manifest   # must run before type-checking
npm ci
npm run build                          # vite build also fails fast if the manifest can't be generated
npm run type-check                     # vue-tsc / tsc sees the generated JSON

Your vue-tsc/tsc step will resolve resources/js/inertia-static.json (or its generated types). If the file is absent, type-checking fails on the import — so the generator must precede it, which is exactly what the release notes call out.

Local development. In vite dev the manifest requirement is a warning, not an error, so a dev server can boot with a stale or missing manifest. Make php artisan inertia-static:manifest part of your composer dev / npm run dev script so it regenerates on boot; otherwise dev-only route references quietly resolve to nothing.

Production builds are a gate. As of v0.4.0 vite build fails if php artisan inertia-static:manifest cannot run. Treat this as a feature: you get a hard failure in CI instead of deploying a client with no static routing. Anything else that invokes vite build — a Node-only Docker stage, a static-site job, a preview deployment — needs PHP and a working artisan bootstrap available.

Formatter handling. Because the JSON is rewritten on every build, exclude it from Prettier/ESLint/dprint explicitly (#ignore / .prettierignore) rather than relying on it being gitignored; editors with format-on-save will otherwise touch it.

Extension point. The generator and the plugin are the two seams. If you need a non-default route subset or path, configure the package and reuse the same artisan command in scripts — do not post-process the JSON by hand, it will be overwritten.

Gotchas and Tips

• vite build now needs PHP. The biggest operational change in v0.4.0. Multi-stage Dockerfiles that only install Node in the build stage will break. Add PHP + composer install (or at least a PHP runtime with artisan) to the build stage, and be aware artisan bootstrapping means your .env/APP_KEY situation must not throw.
• Committed manifests fight the formatter and the build. If you upgraded from an older setup where resources/js/inertia-static.json was checked in, remove it from the index: git rm --cached resources/js/inertia-static.json, add it to .gitignore. Otherwise every build creates churn and merge conflicts.
• Stale manifests don't fail in dev. vite dev only warns, so a route added by a teammate may 404 on links until you regenerate. If you see "route not found" during local development, run the manifest command first, then reload.
• Tests only warn too. Keep a test asserting the manifest command exits successfully, rather than relying on a build test to catch a broken generator.
• Run the doctor in CI. inertia-static:doctor only checks that .gitignore lists the manifest — it does not validate route contents. A one-line CI step catches the "someone removed the ignore entry" regression before it hits a review.
• Build failure messages point at the plugin. When the production build aborts, the underlying cause is an artisan failure (permissions, missing .env, DB-dependent route files). Re-run the artisan command directly to see the real error.
• Debugging missing routes: generate the manifest, inspect the JSON, then check the Vite plugin's behavior — the plugin and the artisan command share this file, which is the single source of truth to inspect.