Wayfinder Laravel Package

Product Decisions This Supports

• Frontend architecture: TypeScript adoption for Laravel apps. Wayfinder removes the single biggest friction point in putting React/Vue/Svelte + TypeScript in front of a Laravel backend — the hand-maintained "route string" layer. If your roadmap item is "migrate our Blade/jQuery frontend to Inertia + React with TS," this package materially de-risks and shortens that work.
• Build vs. buy: build. The alternative is a homegrown route-name-to-URL helper, a hand-written routes.ts constants file, or a custom codegen script. All of those are ongoing maintenance liabilities that drift silently from the backend. Wayfinder is first-party Laravel, MIT, and generated output is disposable (gitignored, rebuilt every build) — the build-vs-buy call is close to free.
• Roadmap option value: API contract safety without an API spec. This is not OpenAPI/GraphQL-style schema tooling, but it delivers a similar outcome for server-rendered and Inertia apps: backend route changes surface as TypeScript compile errors in the frontend rather than as 404s in production. That converts a class of runtime incidents into build failures — a cheap, measurable reliability win.
• Feature scoping: conventional forms and progressive enhancement. The --with-form / .form() variants let you ship plain HTML <form> submissions (including _method spoofing) without a client-side fetch layer. This supports decisions like "do we need a JS-heavy SPA form component, or can this page be a form post?" — useful for scope-cutting on low-interactivity screens.
• Query-string and filter UX decisions. Typed query / mergeQuery options (including null to strip a parameter) make it trivial to model filters, pagination, and sort state as URL state. This supports the product decision to make list views shareable/bookmarkable rather than held in client memory.
• Use cases that fit cleanly: Inertia apps (documented first-class useForm().submit() and <Link href> integration), Laravel + React/Vue with any data-fetching layer, multi-page apps with a smattering of JS, and teams whose frontend and backend are maintained by different people (the generated types become the handshake).
• Team scaling / onboarding. New frontend hires stop needing to learn your route names and URI conventions; they import a typed function and the editor tells them the parameter shape. That's a real, if soft, productivity and onboarding metric.

When to Consider This Package

Adopt when most of these are true:

• You have a Laravel backend with a JS/TS frontend — especially Inertia, but also plain React/Vue with axios/fetch.
• Your frontend already uses TypeScript (or is about to). Without TS, you still get value from URL generation, but you lose the type-safety payoff that justifies the tooling.
• Your app has a meaningful number of routes — roughly 30+ named routes/controller actions is where hand-maintained URL constants start to hurt. Below that, the setup cost isn't obviously repaid.
• Your build pipeline is Vite (Laravel's default). The companion @laravel/vite-plugin-wayfinder makes regeneration automatic on file change; without Vite you're scripting php artisan wayfinder:generate yourself.
• Your team is willing to accept a beta dependency and pin versions. It's v0.1.x with an explicit "API subject to change before v1.0.0" notice.

Look elsewhere or wait when:

• Non-JS frontends, mobile clients, or third-party API consumers. Wayfinder generates TypeScript only. If you need a language-agnostic contract, an OpenAPI spec (via Scramble or similar) is the right tool — and arguably a better fit for public APIs.
• You need a stable, versioned public API surface. Beta churn is fine for internal apps, not for a contract you've published.
• Maturity-sensitive environments. 0 dependents and a sub-1.0 version mean no ecosystem battle-testing; the changelog is dominated by small edge-case fixes (reserved keywords, barrel name collisions, nested route names, Postgres int types, ForcedRoot domain handling). That is normal for a young codegen tool, but it tells you edge cases are still being found.
• You can't absorb a deploy-pipeline change. The documented route:cache staleness issue is the sharpest operational edge here: if your deploy runs php artisan optimize before npm run build, generation runs against a stale route table and Vite fails with missing-module errors. This must be a deliberate, documented step (route:clear → npm run build), not an afterthought. Teams with rigid or heavily cached deploy pipelines should scope that work before committing.
• Bundle-size-sensitive apps that would import whole controllers. Importing PostController rather than named action functions defeats tree-shaking. The guidance exists, but it's a footgun you must codify in lint rules or conventions.
• Multiple routes pointing at the same controller method. The generated export becomes a non-callable dictionary keyed by URI, which is a confusing ergonomic cliff. If your routing does this often, the named-routes import path should become your team's default convention.

Net read: the case for adoption is strong for Inertia/TS Laravel teams and weak-to-premature everywhere else. The two genuine risks are beta API churn and the route-cache deploy ordering — both manageable, neither free.

How to Pitch It (Stakeholders)

For executives — one paragraph: Laravel Wayfinder is a free, MIT-licensed, first-party Laravel package that automatically generates typed TypeScript functions from our backend routes and controllers. In plain terms: the frontend can no longer build against a URL that doesn't exist. Route mistakes that today show up as production 404s and broken links become build-time errors caught before deploy. It's a small, contained addition — no new service, no vendor contract, no data migration — and the generated code is disposable, so there's no long-term lock-in.

For engineering — the substance: Install laravel/wayfinder plus the @laravel/vite-plugin-wayfinder Vite plugin; the plugin regenerates types during dev-server file changes and on build. Generated output (resources/js/{wayfinder,actions,routes}) is gitignored and rebuilt every build, so there's no review noise and no merge conflicts. We get fully typed action functions with flexible argument shapes (positional, keyed object, nested, route-model-binding aware e.g. {post:slug}), .url() / .head() / .form() variants, typed query and mergeQuery options for URL-state filtering, and first-class named-route imports which sidestep the multi-route-to-one-action edge case. Inertia integration is documented and direct: form.submit(store()) and <Link href={show(1)}>. Known edges we should decide on up front: the package is beta (pin the version, expect minor churn); importing an entire controller defeats tree-shaking, so we standardize on per-action and named-route imports; and deploy scripts must run php artisan route:clear before npm run build to avoid generating against a stale route cache.

The decision being asked for: approve a time-boxed pilot on one TS/Inertia surface plus a documented deploy-script change, with success measured by (a) zero frontend-originated 404s from route drift in that surface, and (b) removal of any hand-maintained route constant file.