Routes | typescript-transformer | Spatie SPATIE TypeScript Transformer ========================= spatie.be/open-source [Docs](https://spatie.be/docs) [Typescript-transformer](https://spatie.be/docs/typescript-transformer/v3) Laravel Routes 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) Routes - [ 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) - [ The manifest file ](https://spatie.be/docs/typescript-transformer/v3/advanced/the-manifest-file) Routes ====== ### On this page 1. [ Handling unknown routes ](#content-handling-unknown-routes) Laravel provides a great way to define routes and then generate URLs to those routes in PHP using the `route()` helper. While this all works in PHP, it can be a bit of a pain to do the same in TypeScript. TypeScript transformer can help you here by providing exact copy of the `route()` helper in TypeScript. To add the helper, add the following provider to your `TypeScriptTransformerServiceProvider`: ``` use Spatie\LaravelTypeScriptTransformer\TransformedProviders\LaravelRouteTransformedProvider; protected function configure(TypeScriptTransformerConfigFactory $config): void { $config->provider(new LaravelRouteTransformedProvider()); } ``` The next time you run the `typescript:transform` command, a TypeScript function called `route` will be generated in the `helpers/route.ts` file. You can now use the `route` function in your TypeScript code like this: ``` import {route} from './helpers/route'; // Without parameters const indexUrl = route('users.index'); // https://laravel.dev/users // With parameters const userUrl = route('users.show', {user: 1}); // https://laravel.dev/users/1 ``` TypeScript will be smart enough to provide you autocompletion on these controllers and their parameters. Handling unknown routes ----------------------------------------------------------------------------------------------------------------------------- The generated `route()` helper throws an error when called with a name that does not exist in the manifest. This mirrors Laravel's server-side `route()` behavior (which throws a `RouteNotFoundException`) and surfaces typos at the call site rather than silently producing broken URLs. ``` route('does-not-exist'); // throws: Route "does-not-exist" not found. ``` In well-typed TypeScript code this is impossible to hit. The signature constrains `name` to keys of the generated `RouteParameters` type, so the type checker will reject unknown names before the call is ever made. When you do work with dynamic names (locale-aware routing wrappers, runtime-composed keys), use the `hasRoute` predicate to guard the call: ``` import {route, hasRoute} from './helpers/route'; function safeRoute(name: string) { if (hasRoute(name)) { return route(name); } return null; } ``` `hasRoute` is a type predicate, so inside the guarded branch TypeScript narrows `name` to `keyof RouteParameters`. That means the subsequent `route(name)` call type-checks even when `name` started as a plain `string`. You can exclude certain routes from being included in the generated TypeScript using [route filters](/docs/typescript-transformer/v3/laravel/route-filters). By default, the helper will generate absolute URLs meaning it includes the app URL. This URL will be fetched from the window object in JavaScript. If you want to generate relative URLs instead, you can pass `false` as the third parameter, indicating you don't want absolute URLs: ``` const indexUrl = route('users.index', {}, false); // /users ``` The default value of the absolute parameter can be changed by setting a default for the provider: ``` $config->provider(new LaravelRouteTransformedProvider( absoluteUrlsByDefault: false, )); ``` Now when using the `route` helper in TypeScript, URLs will be relative by default: ``` const indexUrl = route('users.index'); // /users ``` TypeScript transformer will automatically generate the `helpers/route.ts` file in the output directory you configured for TypeScript transformer. It is possible to change the path of this file as such: ``` $config->provider(new LaravelRouteTransformedProvider( path: 'route.ts', )); ``` When running in the watch mode of the package, the generated `route.ts` file will automatically be updated when you change your routes in Laravel. By default, the watcher will monitor the following directories for changes: - `routes` - `bootstrap` - `app/Providers` It is possible to customize the directories that are monitored as such: ``` $config->provider(new LaravelRouteTransformedProvider( routeDirectories: [ 'custom/routes/directory', 'another/directory/to/watch', ], )); ``` 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)