Typescript Transformer Laravel Package

Getting Started

Install the package via Composer: composer require spatie/typescript-transformer --dev. Next, publish the config with php artisan vendor:publish --provider="Spike\TypeScriptTransformer\TransformerServiceProvider". The config file (config/typescript-transformer.php) defines which classes get transformed, output paths, and transformer rules. Start by annotating a simple PHP DTO with typed properties (e.g., class UserDto { public function __construct(public string $name, public int $age) {} }), then run php artisan typescript:transform. The output .d.ts file (default: typescript-transformer.d.ts) appears in the configured directory and includes generated interfaces.

Implementation Patterns

• DTO-first workflow: Define your data structures in PHP DTOs (e.g., using Spatie\DataTransferObject or plain typed classes), then auto-generate TS types. This ensures request/response contracts stay consistent across layers.
• Build pipeline integration: Add php artisan typescript:transform to your CI (e.g., in deploy or build scripts) and include the generated .d.ts in frontend type-checking. You may also hook it into Laravel Mix/Vite builds for runtime-free type generation.
• Enum alignment: Use PHP 8.1+ backed enums for statuses or categories; the transformer automatically produces union types (e.g., type Status = 'draft' | 'published').
• Custom transformers: Extend Transformer for project-specific logic (e.g., renaming fields via @Type("customName"), handling Laravel’s Collection as Array<T>), and register them in the config.
• Selective inclusion: Use the transform method’s only/except filters or @TypeScript annotations on classes to control what gets emitted.

Gotchas and Tips

• Nullability quirks: PHP’s nullable types (e.g., ?string, string|null) map to string | null by default, but null becomes optional only when combined with default values (= null). Verify generated types for optional vs nullable fields.
• Docblock inference: The transformer reads type hints and PHPDoc (e.g., @var or @param). Be precise—e.g., @var string[] for arrays, otherwise it may default to mixed[].
• Collections & generic limitations: Laravel’s Collection becomes any[] unless you configure a custom transformer. For typed arrays, prefer native PHP arrays (array|Class[]) or explicitly annotate in PHPDoc.
• Namespace collisions: If multiple classes share the same short name (e.g., User in App\Models and App\DTOs), use custom naming via namespaceAlias or className transformers to avoid overwrites.
• Testing output: Run the command in verbose mode (-v) to see which classes are processed, and inspect the generated file in CI for unintended drift. Committing .d.ts (not just the generation step) enables frontend linting and diff visibility.