Laravel Stoli Laravel Package

Product Decisions This Supports

• Contract-drift reduction as a roadmap investment. Stoli turns each Laravel route file into a single <Module>Routes definition that every consumer (createRoute(), RouteService, routers, URL helpers) reads from. That makes "typed frontend contract" a property of the codebase rather than a convention someone has to remember — a defensible line item in a platform/DevEx roadmap rather than a nice-to-have.
• Build vs. buy for type generation. The realistic alternative is a hand-rolled script that reflects on routes and emits .d.ts files. Stoli already covers the hard parts: where constraints, backed enums, int route args, route-model binding, laravel-data wrapping/pagination, FormRequest rules() including subclasses, method spoofing, file uploads, and typed validation errors. Choosing to adopt is usually cheaper than owning that generator.
• Frontend architecture decisions. Supports SPA / Inertia / mobile-client roadmaps where a TS client consumes a JSON API: the 'client' => 'fetch' | 'axios' switch and per-route tree-shakeable URL functions ('urls' => true) let you standardize on one HTTP layer without forking the generator.
• CI gating as a policy decision. stoli:generate --check fails the build on stale generated files. This is the lever that converts "types are usually up to date" into "types cannot be out of date" — a workflow decision, not just a tool decision.
• Pipeline consolidation. Because it runs inside typescript:transform (including --watch) and reads the same types the transformer writes, it removes a second codegen step from the build. Fewer moving parts in CI and local dev is a concrete velocity win to weigh against adoption cost.
• Use cases to prioritize: admin/internal dashboards on Laravel + Vue/React, customer-facing SPAs, mobile app backends, and any Laravel app already leaning on spatie/laravel-data or FormRequests for validation.
• Stability signal. v1.0.0 is the first release with an implied API commitment. That is the point at which "pilot on one module" becomes a reasonable proposal; it is also the point where the 0.x → 1.0 breaking changes below become a one-time, budgetable migration instead of ongoing churn.

When to Consider This Package

Adopt when most of these hold:

• Laravel (11+/12/13) backend exposing a JSON API consumed by a TypeScript frontend — SPA, Inertia, or a mobile client.
• You have already felt contract drift: renamed fields, missing params, wrong status handling, any creeping into API calls.
• Requests are modeled with laravel-data (v4 is now required) and/or FormRequests with rules(), so the generator has real types to read.
• Your build runs spatie/laravel-typescript-transformer, or you are willing to add it; CI can run stoli:generate --check.
• Runtime stack is inside the tested matrix: PHP 8.2–8.5, Laravel 12/13, Node 20–24, TypeScript 5.8+.
• You want compile-time types, not runtime validation — this generates types only.

Look elsewhere when:

• No TypeScript consumer: Blade/Livewire-only apps get essentially nothing from it.
• You need a language-agnostic, externally published API contract. An OpenAPI-first workflow with a spec-driven generator serves public/partner APIs better; Stoli is a Laravel-to-TS convenience, not an API documentation tool.
• Your frontend needs runtime schema validation (Zod/Valibot-style parsing of untrusted payloads). Generated types are erased at compile time; pair with a validator rather than substituting this for one.
• You are pinned below the floor: spatie/laravel-data 4 is mandatory, and PHP < 8.2 or older Laravel/Node/TS versions are out of scope.
• You cannot tolerate code generation in the build. If a committed-generated-code policy or single-file ownership is a hard constraint, the --watch/transform coupling will fight your process.
• Small surface area (a handful of endpoints) where the setup cost exceeds the drift risk.

Upgrade cost from 0.x — budget it explicitly: stoli.js/stoli.d.ts become stoli.ts (old files are deleted on next run, so expect a diff); createURLWithoutQuery() is replaced by resolve() and now returns leftover params instead of discarding them (call sites need review); a request's parameters are now its input type (StoreUserDataInput) rather than its Data type; unresolvable responses become unknown instead of Record<string, unknown> (may surface new type errors that were previously masked); 'axios' => true still works but 'client' => 'axios' is preferred; 'transform' => false keeps Stoli's output separate if you need it decoupled.

How to Pitch It (Stakeholders)

Executives: This closes a recurring class of integration bugs — frontend and backend disagreeing about a field, a parameter, or a status code — by generating the TypeScript contract from the Laravel routes themselves, so the two cannot drift silently. The build fails when they do. The cost is a one-time setup plus a bounded 0.x→1.0 migration; the return is fewer QA cycles and faster, safer frontend delivery on every API change. It is a v1.0 with a committed API, tested end to end across PHP 8.2–8.5, Laravel 12/13, Node 20–24, and current TypeScript, so the platform-support risk is low.

Engineering: One definition per route file is the only source of truth; createRoute(), RouteService, both routers (fetch or axios behind one API), and the URL functions all read it, so they cannot contradict each other. It runs inside typescript:transform — --watch included — off the types the transformer already writes, so there is no second pipeline; stoli:generate --check makes staleness a CI failure. Coverage that matters day to day: typed request inputs from laravel-data and FormRequest rules() (nested/recursive Data included), narrowed params from where constraints, backed enums, int args and route-model binding, typed responses and statuses (PHPDoc converted recursively, pagination, 201 on POST), file uploads and method spoofing, typed validation errors keyed by route field, and tree-shakeable per-route URL functions. Note the migration items: stoli.ts rename, resolve() semantics change, request-params-are-input-type, and unknown for unresolvable responses. Pilot on one module, wire --check into CI, then expand.