Running TypeScript Transformer for the first time | typescript-transformer | Spatie SPATIE TypeScript Transformer ========================= spatie.be/open-source [Docs](https://spatie.be/docs) [Typescript-transformer](https://spatie.be/docs/typescript-transformer/v3) Getting-started Running TypeScript Transformer for the first time Version v3 v2 v1 Other versions for crawler [v3](https://spatie.be/docs/typescript-transformer/v3) [v2](https://spatie.be/docs/typescript-transformer/v2) [v1](https://spatie.be/docs/typescript-transformer/v1) Running TypeScript Transformer for the first time - [ Introduction ](https://spatie.be/docs/typescript-transformer/v3/introduction) - [ Postcardware ](https://spatie.be/docs/typescript-transformer/v3/postcardware) - [ Installation ](https://spatie.be/docs/typescript-transformer/v3/installation) - [ Questions & issues ](https://spatie.be/docs/typescript-transformer/v3/questions-and-issues) - [ Changelog ](https://spatie.be/docs/typescript-transformer/v3/changelog) - [ About us ](https://spatie.be/docs/typescript-transformer/v3/about-us) Getting started --------------- - [ Setting up ](https://spatie.be/docs/typescript-transformer/v3/getting-started/setting-up) - [ Running TypeScript Transformer for the first time ](https://spatie.be/docs/typescript-transformer/v3/getting-started/first-run) - [ Special attributes ](https://spatie.be/docs/typescript-transformer/v3/getting-started/attributes) - [ Typing properties ](https://spatie.be/docs/typescript-transformer/v3/getting-started/typing-properties) - [ Replacing common types ](https://spatie.be/docs/typescript-transformer/v3/getting-started/replacing-types) - [ Formatters ](https://spatie.be/docs/typescript-transformer/v3/getting-started/formatters) Laravel ------- - [ Installation and setup ](https://spatie.be/docs/typescript-transformer/v3/laravel/installation-and-setup) - [ Laravel Data ](https://spatie.be/docs/typescript-transformer/v3/laravel/laravel-data) - [ Controllers ](https://spatie.be/docs/typescript-transformer/v3/laravel/controllers) - [ Routes ](https://spatie.be/docs/typescript-transformer/v3/laravel/routes) - [ Route filters ](https://spatie.be/docs/typescript-transformer/v3/laravel/route-filters) - [ Watch mode ](https://spatie.be/docs/typescript-transformer/v3/laravel/watch-mode) Custom transformers ------------------- - [ Getting started ](https://spatie.be/docs/typescript-transformer/v3/transformers/getting-started) - [ Class transformer ](https://spatie.be/docs/typescript-transformer/v3/transformers/class-transformer) - [ Enum transformer ](https://spatie.be/docs/typescript-transformer/v3/transformers/enum-transformer) Transformed providers --------------------- - [ Getting started ](https://spatie.be/docs/typescript-transformer/v3/providers/getting-started) - [ Using different writers in providers ](https://spatie.be/docs/typescript-transformer/v3/providers/writers-in-providers) - [ Logging in providers ](https://spatie.be/docs/typescript-transformer/v3/providers/logging) - [ Referencing types ](https://spatie.be/docs/typescript-transformer/v3/providers/references) - [ Helpers ](https://spatie.be/docs/typescript-transformer/v3/providers/helpers) TypeScript nodes ---------------- - [ Introduction ](https://spatie.be/docs/typescript-transformer/v3/typescript-nodes/introduction) - [ Building your own TypeScript node ](https://spatie.be/docs/typescript-transformer/v3/typescript-nodes/custom-nodes) - [ Visiting TypeScript nodes ](https://spatie.be/docs/typescript-transformer/v3/typescript-nodes/visitor) - [ Node reference ](https://spatie.be/docs/typescript-transformer/v3/typescript-nodes/reference) Watch mode ---------- - [ How does it work? ](https://spatie.be/docs/typescript-transformer/v3/watch-mode/how-it-works) - [ Setting up the runner ](https://spatie.be/docs/typescript-transformer/v3/watch-mode/setting-up-the-runner) - [ Watch events ](https://spatie.be/docs/typescript-transformer/v3/watch-mode/watch-events) - [ PHP Nodes ](https://spatie.be/docs/typescript-transformer/v3/watch-mode/php-nodes) Advanced -------- - [ Extensions ](https://spatie.be/docs/typescript-transformer/v3/advanced/extensions) - [ Managing transformers ](https://spatie.be/docs/typescript-transformer/v3/advanced/managing-transformers) - [ Loggers ](https://spatie.be/docs/typescript-transformer/v3/advanced/loggers) - [ Custom writers ](https://spatie.be/docs/typescript-transformer/v3/advanced/custom-writers) Running TypeScript Transformer for the first time ================================================= TypeScript transformer is a highly configurable framework to transform PHP classes and more into TypeScript types, we provide some highly used functionality out of the box, but you can configure it to your needs. We're going to start with transforming basic PHP classes to TypeScript types, this is what the package actually does: 1. It starts searching for PHP classes within your application 2. It makes a ReflectionClass from each of these found classes 3. These ReflectionClasses are then processed by a list of transformers (they take a ReflectionClass and try to make a TypeScript type from it) 4. If a ReflectionClass is transformed, it is added to a list to be written to TypeScript otherwise the class is ignored 5. That list is then written to a TypeScript file Transformers are the most important part in this whole process, they implement the `Transformer` interface which looks like this: ``` interface Transformer { public function transform(ReflectionClass $reflectionClass, TransformationContext $context): Transformed|Untransformable; } ``` By default, the package comes with a few transformers: - `EnumTransformer`: Transforms PHP enums to TypeScript enums - `ClassTransformer`: Transforms PHP classes with its properties to TypeScript types (abstract, read on for more info) - `AttributedClassTransformer`: A special version of the `ClassTransformer` that only transforms classes with the `#[TypeScript]` attribute - `InterfaceTransformer`: Transforms PHP interfaces to TypeScript interfaces If you're using our Laravel package, you also get access to: - `LaravelAttributedClassTransformer`: A special version of the `ClassTransformer` with some goodies for Laravel users You're free to mix and match these transformers to your needs, or even create your own transformers. Registering can be done as such within your TypeScript CLI command or `TypeScriptTransformerServiceProvider` (if you're using Laravel): ``` $config->transformer(AttributedClassTransformer::class); ``` Since transformers are just PHP classes, you can also pass them arguments when initializing them: ``` $config->transformer(new EnumTransformer(useNativeEnums: true)); // transformers enums as TypeScript native enums and not as a union of strings ``` Quick note: transformers are executed in the order they are registered in the configuration, when a transformer cannot transform a class, the next transformer is checked. Transformers work on PHP classes, we need to tell TypeScript transformer where to look for these classes. This can be done by adding a directory to the configuration: ``` $config->transformDirectories(app_path()); ``` We're almost done! The last thing we need to do is tell TypeScript transformer how to write types. The package comes with three writers: **GlobalNamespaceWriter** Generates a single TypeScript file which exports all types to the global namespace. That namespace is based upon the location of the type. The GlobalNamespaceWriter will always generate a declation TypeScript file with a `.d.ts`extension which means that only types are allowed in this file and executable code is prohibited. **FlatModuleWriter** Creates one module for all transformed objects in a single TypeScript file. The file will contain all transformed objects (types & executable code) without any namespaces. **ModuleWriter**An extension of the FlatModuleWriter which creates a file per location. Each file will contain all transformed objects ( types & executable code) for that location without any namespaces. This can be done by using the `GlobalNamespaceWriter` which writes all types to a single TypeScript file with namespaces: ``` declare namespace App.Data { export type PostData = { title: string; slug: string; type: App.Enums.PostType; tags: Array; publish_date: string | null; published: boolean; }; } declare namespace App.Enums { export type PostType = 'news' | 'blog'; } ``` You can configure this writer as such: ``` $config->writer(new GlobalNamespaceWriter()); ``` The directory where the types should be written to needs to be configured as well: ``` $config->outputDirectory(__DIR__.'/generated'); ``` If you want a file per namespace, then you can use the `ModuleWriter`, it will write a structure like this: ``` // app/data/index.d.ts export type PostData = { title: string; slug: string; type: App.Enums.PostType; tags: Array; publish_date: string | null; published: boolean; }; // app/enums/index.d.ts export type PostType = 'news' | 'blog'; ``` You can configure it like this: ``` $config->writer(new ModuleWriter()); ``` That's it! You're now ready to transform your PHP classes to TypeScript types. If you've configured the `EnumTransformer` then running following command: ``` // on Symphony php bin/console typescript:transform // on Laravel php artisan typescript:transform ``` Should transform every enum into TypeScript. When using the `AttributedClassTransformer`, be sure to add the `#[TypeScript]` attribute to classes you want transformed. A good match? ------------- ### What we do best - All things Laravel - Custom frontend components - Building APIs - AI-powered features - Simplifying things - Clean solutions - Integrating services ### Not our cup of tea - WordPress themes - Cutting corners - Free mockups to win a job - "Just execute the briefing" In short: we'd like to be a **substantial part** of your project. [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)