README

Laravel TypeBridge

Deterministic TypeScript generation from Laravel resources.

Why this package

This package helps you keep backend resources and frontend types aligned, with deterministic output and predictable imports.

Requirements

• PHP >=8.2
• Laravel 12.x or 13.x
• Note: Laravel 13.x requires PHP >= 8.3 (Laravel framework requirement)

Installation

composer require --dev evanschleret/laravel-typebridge

Publish the config:

php artisan vendor:publish --provider="EvanSchleret\\LaravelTypeBridge\\TypeBridgeServiceProvider" --tag=typebridge-config

Generated file:

• config/typebridge.php

Basic usage

Generate files:

php artisan typebridge:generate

Use another output directory:

php artisan typebridge:generate --output-path=resources/typescript

Preview only (no write):

php artisan typebridge:generate --dry-run

Generate and remove stale .ts files:

php artisan typebridge:generate --clean

Generate only selected resources:

php artisan typebridge:generate --only=User,Role

Generate everything except selected resources:

php artisan typebridge:generate --except=Membership

Check generated files in CI:

php artisan typebridge:check

Attribute example

Use TypeBridgeResource on Laravel resources (JsonResource or ResourceCollection):

<?php

declare(strict_types=1);

namespace App\Http\Resources;

use App\Models\User;
use EvanSchleret\LaravelTypeBridge\Attributes\TypeBridgeResource;
use Illuminate\Http\Resources\Json\JsonResource;

#[TypeBridgeResource(
    name: 'UserItem',
    structure: [
        'id' => 'number',
        'email' => 'string|null',
        'roles' => '@relation(roles)',
        'manager?' => '@relation(manager)',
    ],
)]
final class UserResource extends JsonResource
{
    public static string $model = User::class;
}

Optional attribute fields:

• types: local TypeScript aliases/enums declared in the same generated file
• fileName: per-resource output filename override
• append: per-resource lines appended at the end of the generated file
• aliasBase and aliasPlural: alias placeholders used by generation.append_templates

@relation(name) is strict:

• the resource model must be resolvable
• the relation method must exist
• the relation method must return an Eloquent relation

If the relation exists but no generated TypeScript type is available for the related model, the field falls back to any or any[].

@enum(Fully\\Qualified\\EnumClass) generates a TypeScript literal union from PHP enum cases.

Configuration

Published default config

This is the default config generated by vendor:publish:

<?php

declare(strict_types=1);

return [
    'output' => [
        'base_path' => resource_path('typescript'),
        'additional_paths' => [],
    ],
    'sources' => [
        app_path('Http/Resources'),
    ],
    'generation' => [
        'use_semicolons' => false,
        'indent_size' => 2,
        'generate_index' => true,
        'shared_file' => '_api',
        'shared_append' => [],
        'append_templates' => [],
    ],
    'files' => [
        'extension' => 'ts',
        'naming_pattern' => '{name}',
    ],
];

Advanced config example (API wrappers + aliases)

This is an example, not the default:

'generation' => [
    'indent_size' => 4,
    'shared_file' => '_api',
    'shared_append' => [
        'export interface ApiItemResponse<T> {',
        "  status: 'success' | 'error'",
        '  data: T',
        '}',
        'export interface ApiCollectionResponse<T> {',
        '  data: T[]',
        '}',
    ],
    'append_templates' => [
        [
            'name_ends_with' => 'Item',
            'lines' => [
                'export type {base} = ApiItemResponse<{name}>',
                'export type {basePlural} = ApiCollectionResponse<{name}>',
            ],
        ],
    ],
],

Additional outputs

output.additional_paths are generated on every typebridge:generate call when --output-path is not used.

If you use --output-path, additional paths are skipped unless you pass --with-additional-paths.

With RoleItem, this can generate:

export type Role = ApiItemResponse<RoleItem>
export type Roles = ApiCollectionResponse<RoleItem>

Naming placeholders

For files.naming_pattern:

• {name}
• {pascal}
• {camel}
• {snake}
• {kebab}

Example:

'files' => [
    'naming_pattern' => '{kebab}.types',
],

Template placeholders

Inside append_templates.*.lines:

• {name}: resource name
• {base}: alias base (aliasBase or suffix stripping)
• {basePlural}: alias plural (aliasPlural or pluralized base)
• {pascal}
• {camel}
• {snake}
• {kebab}

Override rules

• fileName on the attribute overrides files.naming_pattern for one resource
• --output-path overrides output.base_path

Roadmap

• Add typebridge:check for CI (no write, non-zero exit code when generated files are out of date)
• Add --only and --except to generate a subset of resources
• Add --clean to remove stale generated files
• Improve @relation(...) diagnostics with more actionable error messages
• Add enum helpers (for example @enum(...) support)
• Add configurable scalar mapping presets (datetime, uuid, decimal, etc.)
• Add configurable import/path strategy options
• Add a first-class paginator wrapper preset
• Add pre/post render hooks for advanced customization
• Add incremental generation mode for large codebases
• Add stubs/scaffolding helpers for #[TypeBridgeResource]
• Add optional targets beyond interfaces (for example Zod schema generation)

Other packages

If you want to explore more of my Laravel packages:

• evanschleret/lara-mjml
• evanschleret/laravel-user-presence
• evanschleret/formforge

Open source

• Contributing guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md
• License: LICENSE