Typescript Transformer Laravel Package

Product Decisions This Supports

• Build vs. buy on type generation. The alternative is a bespoke codegen script or hand-maintained .d.ts files that drift. This package converts annotated PHP classes, enums, interfaces, and DTOs into TypeScript types, so "buy" (adopt, MIT, zero license cost) is a low-commitment default unless we have a non-PHP backend.
• Whether to make the backend the source of truth for the API contract. Adopting it is effectively a decision that PHP models define the shapes the frontend consumes. That is a strategic call about where contract ownership lives, not just a tooling choice.
• Roadmap sequencing for a typed frontend. Hardening TypeScript (strict mode, removing any at API boundaries) is usually gated on having real types for server payloads. This package is a prerequisite enabler for that work, and a cheap one to spike.
• Feature scoping for shared surface area. Enums, generics (@template), union/nullable types, and array shapes map to concrete product surfaces — status enums, paginated responses, form payloads. We can decide "ship the enum to the frontend as a union type" without a parallel spec document.
• Architecture decision on how types are published. v3's dual writer is a product-facing choice: ModuleWriter emits modules mirroring PHP namespaces for first-party frontend consumption; GlobalNamespaceWriter emits a single .d.ts for global-scope consumers. That affects import ergonomics and whether we can hand types to an external team.
• DX investment bets. v3's AST + visitor pattern and TransformedProvider mean we can inject types that don't originate from PHP classes (e.g., framework collection generics) and post-process the tree. Watch mode (beta) targets the edit loop. Both are candidates for a "reduce frontend friction" initiative rather than standalone roadmap items.
• Prioritizing integration work. The integration surface is small (Composer package, an attribute or two, a config file, a CI step), so it competes well against OpenAPI-driven codegen when the backend is entirely PHP/Laravel.

When to Consider This Package

Adopt when most of these hold:

• Backend is PHP 8.2+ (v3 requirement) and predominantly Laravel/PHP-owned; the frontend is TypeScript.
• We have an observed class of bugs or rework caused by frontend/backend shape drift, or repeated "what does this endpoint actually return" clarification.
• We can treat generated output as a build artifact: run generation in CI, diff or fail on drift, and add Node tooling (npx prettier / eslint formatters) to the pipeline.
• The team already expresses intent through PHP types, attributes, and docblocks — the transformer reads what is there; it does not invent types for untyped code.
• We need types only, and are comfortable pairing with a separate runtime validation layer (Zod or similar). This package generates compile-time types, not runtime validators.

Look elsewhere when:

• The backend is polyglot or not PHP. Schema-first (OpenAPI, GraphQL codegen, Protobuf) is the correct investment; a PHP-only transformer becomes a second, partial contract.
• The API is public or consumed by third parties. An OpenAPI document is the deliverable, not a generated .d.ts. Use this internally at most.
• We need runtime validation from the same source of truth. This is a type emitter; do not let it be pitched as a validation story.
• We are on v2 and cannot absorb a rewrite. v3 is a ground-up rewrite with explicit breaking changes (collectors removed, DtoTransformer removed, TypeReflectors removed, inline types removed) and no upgrade guide. Budget a migration spike or stay pinned.
• The risk bar is high and adoption evidence matters. 403 stars and no dependents in our dataset is thin evidence relative to core Spatie packages. It is well-maintained and well-documented, but it is a supporting tool, not infrastructure to build a platform on. Prefer pinning a version and owning a thin wrapper.

How to Pitch It (Stakeholders)

For executives (one paragraph): A free, MIT-licensed, actively released Spatie package that generates TypeScript types directly from our PHP classes, enums, and DTOs. It removes a recurring category of frontend/backend integration bugs and unblocks tightening TypeScript across the app, at the cost of a Composer dependency and a CI step — no vendor contract, no per-seat licensing, reversible in a sprint if it doesn't pay off. Principal risk is maturity signals: modest adoption (~400 stars, no downstream dependents in our data) and a recent v3 rewrite with no upgrade path, so we pin the version and treat generated files as build artifacts.

For engineering (the substance): Attribute-driven transformation (#[TypeScript]) of classes, enums, interfaces, and DTOs. v3 replaces string generation with a real TypeScript AST plus a visitor pattern for replace/remove passes, swaps PHPDocumentor for PHPStan's type parser (better generics, array shapes, key-of/value-of, unions/intersections), and adds TransformedProvider for injecting types not backed by a PHP class — useful for framework generics. Two writers: per-namespace modules or a single global .d.ts. Prettier and ESLint formatters keep output reviewable, but they mean Node must exist in the build image. Watch mode is beta — do not put it in the critical path. Generation must be deterministic and checked in CI; the 3.1.1 fix that errors on a missing output directory rather than silently resolving to an empty path is exactly the failure mode to guard against.

Risks to state up front: v3 breaking changes with no migration guide (assume a spike, not a lift-and-shift); beta watch mode; a Node dependency for formatting; and a small ecosystem footprint, which argues for a thin internal wrapper so the package is swappable if we later move to schema-first.