Laravel Type Bridge Development

Laravel Type Bridge Development

When to use this skill

Use this skill when:

• Generating TypeScript or JavaScript enums from PHP backed enums
• Generating frontend i18n translation files from Laravel lang files
• Generating enum translator composables for frontend use
• Interacting with or integrating the generated enums/translations/translator composables in frontend code
• Configuring or extending the type bridge generation pipeline

Installation & Setup

composer require gaiatools/laravel-type-bridge
php artisan type-bridge:publish
# Alternative:
# php artisan vendor:publish --tag=type-bridge-config

This publishes config/type-bridge.php where all generation is configured.

Configuration (config/type-bridge.php)

return [
    'output_format' => 'ts',          // 'ts' | 'js'
    'max_line_length' => 120,         // ESLint disable-line threshold (0 to disable)
    'trailing_commas' => true,
    'i18n_library' => 'i18next',      // 'i18next' | 'vue-i18n'

    'enums' => [
        'generate_backed_enums' => true,
        'discovery' => [
            'include_paths' => [app_path('Enums')],
            'exclude_paths' => [],
        ],
        'output_path' => 'js/enums/generated',    // relative to resources/
        'import_base' => '@/enums/generated',
    ],

    'translations' => [
        'discovery' => [
            'include_paths' => [base_path('lang')],
            'exclude_paths' => [],
        ],
        'output_path' => 'js/lang/generated',
        'custom_adapter' => null,    // optional: \App\TypeBridge\CustomI18nAdapter::class
    ],

    'enum_translators' => [
        'discovery' => [
            'include_paths' => [app_path('Enums')],
            'exclude_paths' => [],
        ],
        'translator_output_path' => 'js/composables/generated',
        'utils_composables_output_path' => 'js/composables',
        'utils_composables_import_path' => '@/composables',
        'utils_lib_output_path' => 'js/lib',
        'utils_lib_import_path' => '@/lib',
    ],
];

Artisan Commands

Generate everything (enums + translations + translators)

php artisan type-bridge:generate
php artisan type-bridge:generate en
php artisan type-bridge:generate --enums=Status --enums=App\\Enums\\Role
php artisan type-bridge:generate --translations-format=json

Generate TypeScript/JavaScript enums from PHP backed enums

php artisan type-bridge:enums              # uses config output_format
php artisan type-bridge:enums --format=ts  # force TypeScript
php artisan type-bridge:enums --format=js  # force JavaScript
php artisan type-bridge:enums --check      # CI mode: fails if output is out of sync
php artisan type-bridge:enums --dirty      # only write enums that are out of sync

Input: PHP backed enums in app/Enums/ (e.g. Status::class) Output: resources/js/enums/generated/Status.ts

// !!!!
// This is a generated file.
// Do not manually change this file
// !!!!
export const Status = {
    Active: 'active',
    Inactive: 'inactive',
} as const;

export type Status = typeof Status[keyof typeof Status];

Generate frontend i18n translation files

php artisan type-bridge:translations en
php artisan type-bridge:translations en --format=json
php artisan type-bridge:translations en --format=js
php artisan type-bridge:translations en --format=ts
php artisan type-bridge:translations en --flat    # flatten nested keys

Input: lang/en/ PHP translation arrays Output: resources/js/lang/generated/en.ts (i18next or vue-i18n syntax based on i18n_library config)

Generate enum translator composables

php artisan type-bridge:enum-translators
php artisan type-bridge:enum-translators --format=ts
php artisan type-bridge:enum-translators --dry    # preview candidates without writing
php artisan type-bridge:publish-translator-utils  # publish shared helper utilities
php artisan type-bridge:publish-translator-utils --force

Output: resources/js/composables/generated/useStatusTranslator.ts

Only enums that are both in the frontend enum generation set and have translations are eligible for translator generation.

Publish translator utilities (required once per project)

php artisan type-bridge:publish-translator-utils [--force]

Defaults (configurable via enum_translators.*):

• composables: resources/js/composables
• lib: resources/js/lib

The file extensions follow type-bridge.output_format.

Using the Generated JavaScript

These examples assume your frontend resolves @ to resources/js (or equivalent) and you are generating JavaScript (output_format = js).

Enums

import { Status } from '@/enums/generated/Status';

if (status === Status.Active) {
    // ...
}

Translations

The translation files are plain objects. The output shape depends on i18n_library.

i18next-style output:

import en from '@/lang/generated/en';

i18next.addResources('en', 'translation', en);

vue-i18n-style output:

import en from '@/lang/generated/en';

const i18n = createI18n({
    locale: 'en',
    messages: { en },
});

Enum Translator Composables

Generated composables return a translator function (with helper methods). The exact API depends on the published utils in js/composables and js/lib.

import { useStatusTranslator } from '@/composables/generated/useStatusTranslator';

const statusTranslator = useStatusTranslator();

statusTranslator('active'); // "Active"
statusTranslator.options(); // [{ value: 'active', label: 'Active' }, ...]

Destructuring is optional if you prefer direct access:

const translateStatus = useStatusTranslator();
translateStatus('active');
translateStatus.options();

Opt-in Enum Generation

Set type-bridge.enums.generate_backed_enums=false to restrict enum output to enums marked with #[GenerateEnum].

use GaiaTools\TypeBridge\Attributes\GenerateEnum;

#[GenerateEnum]
enum ThemeVisibility: string
{
    case Private = 'private';
    case Unlisted = 'unlisted';
    case Public = 'public';
}

Global Translation Engine Setup

Generated translators call a global translation engine. Configure it once at app bootstrap:

import i18n from '@/i18n';
import { configureTranslationEngine } from '@/composables/useTranslator';

configureTranslationEngine({
  t: (key: string) => i18n.t(key),
});

CI Drift Detection

Use --check flag in CI pipelines to fail if generated files are out of sync with source:

# In CI (GitHub Actions, etc.)
php artisan type-bridge:enums --check

Returns non-zero exit code when generated output does not match what would be generated.

Extending the Pipeline

The generation pipeline follows: Discoverer → Transformer → OutputFormatter → FileWriter

To add a custom i18n adapter, implement TranslationSyntaxAdapter and set translations.custom_adapter in config:

'custom_adapter' => \App\TypeBridge\MyAdapter::class,

Discovery paths are fully configurable per generator. Add multiple paths or exclude specific directories using include_paths / exclude_paths arrays in each generator's discovery config block.

File Output Conventions

All generated files include a header warning:

// !!!!
// This is a generated file.
// Do not manually change this file
// !!!!

Files exceeding max_line_length get ESLint disable directives automatically. Set max_line_length to 0 to disable this behavior.

Output paths are always relative to resources/.