Weave Code
Oi Laravel Ts Laravel Package
oi-lab/oi-laravel-ts
A Laravel package that automatically generates TypeScript interfaces from your Eloquent models, with relationship support, custom casts, DataObjects, PHPDoc types, watch mode, and namespace filters for customization.
OI Laravel TypeScript Generator converts your Eloquent models into TypeScript interfaces automatically, capturing relationships, casts, and PHPDoc-annotated types. It runs a two-pipeline architecture—one analyzing models and their metadata, the other emitting clean, typed output—so your frontend types stay in sync with your backend schema.
- Generates interfaces for all Eloquent relationship types and custom casts
- Emits DTO interfaces for spatie/laravel-data style classes, including nested DTOs and enum unions
- Supports watch mode and namespace filters to exclude or extend third-party models
- Types UUID/ULID keys as
stringand integer keys asnumber - Fully configurable, with optional JSON-LD support
Frequently asked questions about Oi Laravel Ts
- How do I install oi-lab/oi-laravel-ts in a Laravel project?
- Install the package with Composer, publish its configuration file, and run the generation command. It is a build-time tool with no runtime dependency, so it does not affect application requests. The published config controls output paths, namespace filters, declaration style, and whether generation reads your database schema.
- Which Laravel versions are supported by oi-laravel-ts?
- The package is designed for Laravel 11, 12, and 13 and integrates directly with Eloquent models. It fits PHP backend teams already using Laravel and does not require a separate schema definition. Check the repository for the latest compatibility notes before upgrading major Laravel versions.
- Does oi-laravel-ts require a live database during type generation?
- Yes by default in v1.2.0 because use_database_schema defaults to true and reads the actual table schema. That makes generated interfaces match what the API serializes, but CI jobs must provision a reachable database. If the database is unreachable, generation silently falls back to fillable, which can produce different types without failing the build.
- How are Eloquent relationships and nested DTOs represented in TypeScript?
- All common relationship types such as HasOne, HasMany, BelongsTo, MorphTo, and through relations are resolved into TypeScript properties. DTOs support enum literal unions and nested DTOs, and data_discriminators emits proper discriminated unions using base intersections. Extension models are emitted as intersections, so a missing base type shows up as a broken intersection.
- Why do JSON, array, or collection casts generate unknown in the output?
- Those casts still emit unknown because the package cannot reliably infer their value shape from the model definition. This is deliberate and safer than falling back to a wrong column type. You can supply explicit shapes with custom_props for the affected properties, and class casts with unreadable value types also emit unknown.
- Can I exclude vendor models or extend existing TypeScript interfaces?
- Yes, excluded_namespaces removes third-party models entirely, while extended_namespaces promotes them to extension interfaces. Misconfigured namespace filters can still lead to broken imports or missing types in generated files. Because extension models are now intersections, a missing base type appears as a broken intersection rather than a missing property.
- Does oi-laravel-ts support watch mode and CI workflows?
- Watch mode monitors your models directory and regenerates TypeScript automatically when files change. CI can run the same generation step, but if database schema mode is enabled the job needs a reachable database. Without one, the silent fillable fallback can make CI succeed with different types, so treat that path as a risk.
- How does declaration_style type improve Inertia useForm integration?
- Setting declaration_style to type makes generated interfaces assignable to Record<string, T>, which is what Inertia's useForm and useHttp expect. That avoids wrapper types or as casts in frontend forms. It closes a real integration gap for Laravel teams using Inertia with TypeScript.
- What output changes should I expect when upgrading to v1.2.0?
- v1.2.0 is semver-minor but changes generated output because use_database_schema now defaults to true. Nullable columns become optional properties typed T or null, which can surface strict-null and exactOptionalPropertyTypes errors in existing frontend code. Treat the upgrade as a coordinated rollout and review generated diffs instead of a drop-in composer update.
- How does oi-laravel-ts compare with writing TypeScript types manually?
- Manual types drift as Eloquent models, casts, and relationships change, while this package regenerates interfaces from the source of truth. It also handles enum literal unions, nested DTOs, smart UUID and ULID primary keys, and watch mode. The tradeoff is that database-aware generation adds a build-time database prerequisite, so teams must decide between schema accuracy and static-only generation.
Weaver
How can I help you explore Laravel packages today?