Laravel Stoli Laravel Package

Technical Evaluation

Architecture fit. This is a build-time codegen tool, not a runtime dependency — it sits in the seam between a Laravel JSON API and a TypeScript client. The core architectural bet is "one definition per route file" (<Module>Routes), with createRoute(), RouteService, the routers, and the URL functions all reading from that single definition. That is the right shape if the problem you actually have is API contract drift between backend and frontend. It is a poor fit if the frontend is Blade/Inertia, if the API is consumed by non-TypeScript clients (mobile, partners), or if the team has not adopted spatie/laravel-data — the release hard-requires Data v4.

Integration feasibility. Tractable but constrained. The effective platform floor is PHP 8.2+, Laravel 12/13, Node 20–24, TypeScript 5.8+, plus spatie/laravel-data 4. That excludes Laravel 10/11 estates entirely — for those, this release is not adoptable without a platform upgrade first. The tested matrix (PHP 8.2–8.5 × Laravel 12/13 × Node 20–24) is unusually broad for a 1.0 and materially lowers integration risk. Integration points are well-defined: typescript:transform (including --watch), or standalone stoli:generate, with --check available as a CI gate.

Technical risk. Moderate, concentrated in the 0.x → 1.0 break rather than in the feature set:

• File rename stoli.js/stoli.d.ts → stoli.ts, with old files removed on next run. Any manual import of the old paths breaks, and committed artifacts linger in VCS history.
• Input-type semantic change: a request's parameters are now its input type (StoreUserDataInput), not its Data type. Call sites typed against the Data type will fail — or, worse, pass structurally while masking validation-shape differences.
• createURLWithoutQuery() → resolve() is a behavior change, not a rename: leftover parameters are returned rather than deleted. Callers relying on deletion can silently leak params into query strings.
• unknown instead of Record<string, unknown> for unresolvable responses is safer but forces narrowing at every affected call site.
• Codegen coupling: correctness depends on routes actually being expressed as <Module>Routes definitions. Routes registered via closures, vendor packages, or ad-hoc Route:: calls fall outside the source of truth and degrade to unknown.
• --check is only as strong as its adoption — nothing enforces it unless CI does.

Key questions.

1. Is there a migration guide beyond the release-notes bullet list, with before/after examples for the input-type and resolve() changes?
2. What is the 1.x support window, and are 0.x patches still being cut? Any public deprecation policy for 'axios' => true vs 'client' => 'axios'?
3. Are generated files intended to be committed (and code-reviewed) or gitignored? What does the maintainer recommend, and why?
4. How are routes registered conditionally, via Route::resource, or inside vendor packages handled?
5. How are non-2xx shapes (401/403/419/429, validation errors outside the route's declared fields) typed — and do they survive php artisan route:cache?
6. Does resolve() handle array/nested/repeated query parameters predictably?
7. Is type information derived purely statically from source, or is there any runtime introspection (and therefore a booted-app requirement in CI)?
8. Is there a versioning story for independently deployed SPAs, or is generation assumed to be lockstep with the backend deploy?

Integration Approach

Stack fit. Strong fit for Laravel 12/13 + spatie/laravel-data 4 + a TypeScript SPA/consumer. Preferable to hand-maintained API clients or an OpenAPI-plus-codegen chain if the team is already Data-object-centric — in that case the route definition is the only new artifact. If the team's source of truth is currently an OpenAPI spec, this introduces a second one.

Migration path (sequenced).

1. Freeze and baseline. Branch. Capture current 0.x generated output so you can diff post-migration.
2. Land the Data v4 upgrade independently. The release couples them; don't debug two migrations at once.
3. Bump to 1.0 and regenerate. Expect stoli.js/stoli.d.ts removal — delete from VCS and from every import.
4. Repoint imports to stoli.ts.
5. Run tsc --noEmit to enumerate call sites affected by the input-type change; fix StoreUserData* → StoreUserDataInput in request parameter positions.
6. Audit, don't blind-rename, createURLWithoutQuery() → resolve(). Each call site needs a decision about the returned leftovers.
7. Adopt 'client' => 'fetch'|'axios' explicitly; retain 'axios' => true only if needed and track its removal.
8. Narrow newly-unknown responses at the call sites — this is where latent contract bugs surface; treat each as a real finding, not a type chore.
9. Wire stoli:generate --check into CI before merging the migration branch, so drift can't re-enter.
10. Decide the 'transform' => false question. Co-running inside typescript:transform (the default) means one pipeline and one ordering constraint; separating them means two things to keep in sync.

Compatibility. Hard floors: PHP 8.2, Laravel 12, Node 20, TypeScript 5.8, Data 4. Any unmet floor converts this from a dependency bump into a platform program.

Operational Impact

Maintenance. 1.0 signals semver intent, so future breaks should be major-version events — a meaningful improvement over 0.x. But the surface is wide (route definitions, two routers, URL functions, the generator, transformer integration), and each is a place where a Laravel or Data upgrade can change generated output. Expect regeneration churn on Laravel minors and budget review time for the resulting diffs.

Support. The single largest external risk is the Data v4 dependency; a Data 5 would likely force a Stoli major. Coverage of PHP 8.5, Laravel 13, and Node 24 in the test matrix is a strong liveness signal, but confirm release cadence and issue-response history before committing a roadmap to it.

Scaling. Codegen scales with route count, not traffic — so the concerns are developer-facing: --watch performance on large route sets, TypeScript server responsiveness if everything lands in one stoli.ts, and bundle size. 'urls' => true tree-shakeable URL functions help only if the bundler is actually configured to shake them.

Failure modes.

• Stale types — generated files committed but not regenerated; runtime shape drifts with no compile error. Mitigation: --check gating merges, non-negotiable.
• Silent widening — unresolvable responses become unknown; a team that reflexively casts reacquires the risk it just paid to remove.
• Orphaned 0.x artifacts — stoli.js/stoli.d.ts still imported somewhere; builds pass locally, break after cleanup.
• Route coverage gaps — any route not expressed as a <Module>Routes definition is invisible, reintroducing exactly the drift the package exists to eliminate.
• URL assembly regressions from resolve() returning leftovers — dropped params or stray query strings.
• Deploy skew — nothing in the notes describes versioned/staged generation for a frontend deployed independently of the backend.

Ramp-up. Moderate. Contributors must hold three things at once: Laravel route/Data/FormRequest conventions, the <Module>Routes definition idiom, and the shape of the generated output. The two most common early mistakes will be the input-vs-Data distinction and unknown narrowing. Recommend a short internal guide covering the route-definition pattern and an explicit "regenerate, never hand-edit" rule, plus a named owner for the generated files.

TPM recommendation. Adopt on new Laravel 12+ projects with a TypeScript frontend. For existing 0.x users, treat the upgrade as a scoped, scheduled piece of work with the Data v4 bump landed first and --check enforced in CI before the migration merges. Do not attempt this as a drop-in on Laravel ≤ 11.