Inertia Static Laravel Package

Technical Evaluation

Architecture fit

• The package sits at the intersection of three layers: a Laravel service provider (Artisan commands inertia-static:manifest, inertia-static:doctor), a Vite build plugin, and an Inertia.js client that consumes a generated resources/js/inertia-static.json for static route resolution.
• This is a build-time codegen dependency, not a runtime one. That is architecturally clean (no production request-path coupling) but it hard-couples the PHP and Node toolchains inside a single build step — the Vite plugin must be able to shell out to php artisan in the same environment.
• Fits well for teams already on Laravel + Inertia + Vite + TypeScript. It is a poor fit where PHP and Node are built in separate containers/CI jobs with no shared filesystem or where the frontend is built by a different team than the backend.

Integration feasibility

• Feasible, but the release raises the bar on CI. v0.4.0 requires the manifest to be generated before vue-tsc/tsc runs, and requires the CI job to have a working PHP runtime and a bootable Laravel app at Vite build time.
• The inertia-static:doctor command is a genuinely useful adoption lever: it is a cheap, self-serve preflight check (verifies .gitignore hygiene) that reduces the support surface for platform teams.

Technical risk

• Behavioral break in a 0.x minor. Production vite build previously degraded gracefully (shipped a client without static routing); it now fails hard when inertia-static:manifest can't run. Any existing pipeline where the manifest step was flaky, unconfigured, or silently skipped will now go red — this is a correctness win but a pipeline-breaking event for current adopters. vite dev and tests still only warn, so the failure is asymmetric and will not be caught locally.
• Generated-file workflow migration. resources/js/inertia-static.json is now explicitly a build artifact: must be .gitignored and regenerated in CI. Consumers who currently commit it face a two-sided problem — a noisy rewrite on every build and a formatter/vue-tsc fight on a tracked generated file.
• Pre-1.0 churn. At v0.4.0 the maintainers reserve the right to change behavior in minor releases; treat every bump as potentially breaking until 1.0.
• Dual-runtime failure surface. Failures can originate in PHP (app won't boot, Artisan unavailable in CI image), in Node (plugin invocation, path resolution), or in the contract between them (generated file shape vs. consumer expectations). Diagnostics are split across two toolchains.
• No evidence in the notes on manifest format/versioning, plugin configuration options, or a documented rollback path.

Key questions

1. Is the manifest schema versioned, and will a client built against an older manifest fail loudly or silently misroute?
2. Is there a documented escape hatch (env flag/config) to restore the previous "warn and continue" build behavior during migration?
3. What exactly does the plugin require at build time — full Laravel bootstrap, DB access, env vars, queue/Redis? Is a minimal boot path supported?
4. Is inertia-static:doctor limited to .gitignore checks, or will it validate the manifest step, PHP/Node co-location, and TypeScript ordering? Can it be extended or is it opinionated?
5. What is the support policy across 0.x minors, and is there a target date for 1.0 / an API-stability commitment?

Integration Approach

Stack fit

• Requires: Laravel (recent supported major), Inertia.js, Vite, and TypeScript (vue-tsc or tsc in the pipeline). Non-TypeScript Inertia apps still work but forfeit the main reason to generate the manifest before the typecheck step.
• Strong fit for a monolith/monorepo where one CI job owns both PHP and Node. Weak fit for split frontend/backend repositories or a separate frontend build service — those need an artifact handoff (generate manifest in the PHP job, publish it as a CI artifact into the Node job).

Migration path

1. Pin ^0.4.0 explicitly; do not float on 0.x.
2. Add resources/js/inertia-static.json to .gitignore and git rm --cached it. Run the formatter once after removal to clear lingering diffs.
3. Reorder the CI pipeline: composer install → app bootable → php artisan inertia-static:manifest → vue-tsc/tsc → vite build.
4. Run php artisan inertia-static:doctor as a required CI step (and ideally in the local setup script) so the .gitignore rule cannot regress.
5. Only then upgrade the Vite plugin, since the fail-hard change lands simultaneously.

Compatibility

• The fail-hard build is the compatibility boundary: it is safe for greenfield, and needs an explicit migration ticket for existing adopters. Anyone whose CI image lacks PHP in the Node build stage will break immediately.
• Check Vite major version alignment and Inertia adapter version before upgrading; the notes do not state a peer range.

Sequencing gitignore + doctor first (non-breaking, self-verifying) → CI reordering (non-breaking) → plugin upgrade to v0.4.0 (breaking) → remove any prior workarounds that tolerated a missing manifest. This ordering lets you prove the manifest is reliably generated before you enable the failure mode that depends on it.

Operational Impact

Maintenance

• Low ongoing code footprint, but the pipeline becomes a maintained asset: manifest generation is now a hard prerequisite for release. Budget for a CI-owned step and clear ownership of that step.
• Generated artifact churn disappears once the file is ignored — net reduction in repo noise and merge conflicts, at the cost of one migration cleanup.
• Pre-1.0 means upgrade work each minor; plan a recurring (e.g. quarterly) review rather than pinned-and-forgotten.

Support

• Failure messages shift from "static routing quietly doesn't work in production" (hard to diagnose, discovered by users) to "the build failed" (loud, developer-facing). That is a large support-load improvement and the strongest argument for adopting v0.4.0.
• inertia-static:doctor is a first-line triage tool — document it in the onboarding runbook so teams self-serve instead of escalating.
• Expect a spike of "build now fails" tickets during rollout; pre-announce the change and link the CI reordering steps.

Scaling

• Scales fine horizontally: no runtime component, nothing to provision, no request-path latency. Cost is linear in build count, not traffic.
• The one scaling pressure is CI concurrency and duration — a PHP runtime is now present in the frontend build stage, increasing image size and cold-start. For many apps/services, consider a shared base CI image with PHP + Node preinstalled.
• Parallel builds that both regenerate the manifest are safe if each has its own workspace; shared-workspace parallel jobs are not.

Failure modes

The dev/test-only-warn asymmetry is the most important operational risk: local green does not imply CI green. Require a production build in PR checks.

Ramp-up

• Low for developers — commands are self-explanatory and doctor guides setup.
• Moderate for whoever owns CI. The mental model to teach is: the manifest is a build artifact, generated in CI, consumed by the typechecker and the Vite build, and never committed.
• Estimate: under a day for a single Laravel+Inertia app with an existing CI pipeline; 2–3 days for a multi-app monorepo or split-repo setup needing artifact handoff.
• Adoption recommendation: adopt, contingent on pinning ^0.4.0, completing the .gitignore/CI-ordering migration first, and requiring a production build in PR checks.