Laravel Typescript Transformer Laravel Package

Product Decisions This Supports

• Stricter Type Safety for Frontend Routing: Eliminates runtime errors in Inertia.js, Laravel Livewire, or custom routing libraries by enforcing literal HTTP method unions (e.g., 'get' | 'post' instead of string). Directly addresses flakiness in router.visit() calls and improves IDE autocompletion.
• Performance Optimization via API Surface Pruning: Excludes irrelevant HTTP methods (e.g., HEAD, OPTIONS) from generated types by default, reducing frontend bundle size and unnecessary type checks. Aligns with modern SPAs that rarely use non-standard methods.
• Progressive API Exposure Control: Introduces httpMethodsPriority to curate the API contract—teams can whitelist/blacklist methods (e.g., hide DELETE for SPAs) and control the emitted order. Supports gradual migration of backend endpoints to frontend consumers.
• Inertia.js/Livewire Synergy: Validates the package’s deep integration with Laravel’s frontend ecosystem, reducing friction for teams using these libraries. Ensures type-safe navigation and form submissions out of the box.
• Build vs. Buy Reaffirmation: Reinforces the package’s value over manual type definitions or alternatives like GraphQL codegen by offering auto-generated, optimized, and customizable types for Laravel APIs.

When to Consider This Package

• Adopt When:

  • Your frontend uses Inertia.js, Laravel Livewire, or custom routing libraries requiring literal HTTP method types (not string).
  • You want to minimize frontend bundle size by excluding unused HTTP methods (e.g., HEAD, OPTIONS) from generated types.
  • Your team needs fine-grained control over which controller methods are exposed to the frontend (e.g., hide DELETE for SPAs).
  • You’re migrating from string-based route types to stricter unions (e.g., upgrading from method: string to method: 'get' | 'post').
  • Your Laravel API has stable HTTP methods (dynamic methods may still require manual overrides).
  • You prioritize developer experience (reduced runtime errors, better IDE support) over explicit route definitions.

• Look Elsewhere If:

  • Your frontend doesn’t use Inertia/Livewire and relies on REST/GraphQL clients that tolerate string methods.
  • You need dynamic method generation (e.g., methods added at runtime via middleware).
  • Your team prefers explicitly defining all routes (e.g., via OpenAPI/Swagger) over auto-generating from controllers.
  • You’re using non-Laravel routing (e.g., Symfony’s Attribute routes) that don’t align with this package’s assumptions.
  • You require HEAD/OPTIONS methods in your frontend types (customize httpMethodsPriority to include them).

How to Pitch It (Stakeholders)

For Executives:

*"This update eliminates a class of bugs in our Laravel + TypeScript routing by replacing loose string method types with strict unions like 'get' | 'post'. For teams using Inertia.js or Livewire, this means router.visit() calls are now type-safe by default, reducing flakiness in navigation and form submissions.

Key Impact:

• Smaller, Faster Frontend: Excludes HEAD/OPTIONS from types by default, trimming bundle size without manual effort.
• Proactive API Governance: Teams can whitelist/blacklist HTTP methods (e.g., hide DELETE for SPAs) via httpMethodsPriority, controlling the API surface exposed to the frontend.
• Zero-Cost Optimization: No refactoring required—just configure httpMethodsPriority in config/typescript-transformer.php to start benefiting.

Metric to Track:

• Reduction in frontend bundle size (bytes saved by excluding HEAD/OPTIONS types).
• Decrease in runtime errors related to router.visit() or Inertia navigation.
• Developer productivity gains (time saved debugging loose method types)."

For Engineering Leaders:

*"The 3.2.0 release transforms type safety for routing while giving us explicit control over the API surface. Here’s the breakdown:

New Features:

1. Literal HTTP Method Unions: Generated types now use 'get' | 'post' instead of string, eliminating casts for Inertia/Livewire:

   router.visit(MyController.update()); // Type-safe with `method: 'put'`
   

2. API Surface Pruning: httpMethodsPriority filters and orders emitted methods. Default excludes HEAD/OPTIONS (auto-registered by Laravel but unused in SPAs):

   // config/typescript-transformer.php
   'http_methods_priority' => ['get', 'post', 'patch'], // Only these are emitted
   

3. Progressive Exposure: Hide sensitive methods (e.g., DELETE) from the frontend via the config or #[TypeScript(ignore: true)].

Trade-offs:

• Breaking Change: Existing method: string types in frontend code may need updates (but this is a one-time fix for long-term safety).
• Dynamic Methods: Runtime-added methods (e.g., via middleware) still require manual handling.

Proposal:

1. Pilot: Test with Inertia.js routes to validate type safety gains.
2. Configure: Set httpMethodsPriority to match your SPA’s needs (e.g., ['get', 'post', 'patch']).
3. Deprecate: Phase out custom string-based route types in favor of the new unions.
4. Document: Update frontend docs to reflect the stricter method types.

Migration Path:

# Step 1: Update config
php artisan vendor:publish --tag=typescript-transformer-config

# Step 2: Update frontend types (if using string)
router.visit(MyController.action()); // Now requires explicit method union

Risks Mitigated:

• No impact on backend routes—only frontend types.
• Backward-compatible if you include all methods in httpMethodsPriority."

For Developers:

*"Say goodbye to router.visit(MyController.update()) failing because TypeScript didn’t know update was a 'put' method. 3.2.0 makes it just work:

Before:

router.visit(MyController.update()); // ❌ Error: `method` is `string`, not `'put'`

After:

router.visit(MyController.update()); // ✅ Type-safe! `method` is `'put'`

Bonus: It drops HEAD/OPTIONS from types by default—no more clutter from methods you’ll never use.

How to Use:

1. Configure Priorities:

   // config/typescript-transformer.php
   'http_methods_priority' => ['get', 'post', 'patch'], // Only these methods are emitted
   

2. Hide Methods:

   #[TypeScript(ignore: true)]
   public function destroy() { ... } // Never exposed to frontend
   

3. Customize for Your SPA:
   • Need HEAD? Add it to the priority list.
   • Using DELETE? Keep it or exclude it based on your needs.

Pro Tip:

• Run php artisan typescript:transform after updating the config to regenerate types.
• Use php artisan typescript:watch for live updates during development.

Why This Matters:

• Fewer Bugs: No more runtime errors from loose method types.
• Smaller Types: Less bundle bloat from unused methods.
• More Control: Curate your API surface to match your frontend’s needs."