Download the PHP package rzl-app/ziggy without Composer

Rzl Ziggy – Fully-Typed Laravel Route Generator for JS/TS

(Forked from Ziggy by Tighten).

Rzl Ziggy is a customized fork of Ziggy that provides a fully-typed JavaScript route() function mimicking Laravel's routing, with additional features such as extended config handling and attribute stubs.

This package is not officially maintained by Tighten.

It is framework-agnostic and can be used with Vue, React, Vanilla JS, and other JavaScript-based frontends that rely on Laravel's routing system.

⚡️ Includes a Vite plugin for auto-generating route definitions on the fly from Laravel!

• Installation
• Usage
  • route() function
  • Router class
  • Route-model binding
  • TypeScript Support
• JavaScript frameworks
  • Generating and importing Rzl Ziggy's configuration
  • Importing the route() function
  • Vue
  • React
  • SPAs or separate repos
• Publish Config File
• Filtering Routes
  • Including/excluding routes
  • Filtering with groups
• Default Parameter Values
• Routes File Generator
  • Using JavaScript/TypeScript
  • Output Name File And Path To Generate
• Automatically Regenerates File Routes
• Other
• Contributing

Installation

Install Rzl Ziggy in your Laravel backend with Composer:

Install Rzl Ziggy in your frontend or SPA with NPM:

Add the @rzlRoutes Blade directive to your main layout (before your application's JavaScript), and the route() helper function will be available globally!

By default, the output of the @rzlRoutes Blade directive includes a list of all your application's routes and their parameters. This route list is included in the HTML of the page and can be viewed by end users. To configure which routes are included in this list, or to show and hide different routes on different pages, see Filtering Routes.

Usage

route() function

Rzl Ziggy's route() function works like Laravel's route() helper—you can pass it the name of a route, and the parameters you want to pass to the route, and it will generate a URL.

Basic usage

Absolute URL

The third argument determines whether the generated URL should include the origin. By default, it is false, meaning the URL will be returned without the origin. To include the origin in the result, simply pass true as the third argument.

⚠️ Passing a non-boolean value except null or undefined as the third argument will throw an error.

⚠️ Passing a non-boolean value like null or undefined as the third argument will force to false.

Parameters

⚠️ Warning: Unknown route parameters in Laravel will be appended as query strings with empty values.

Multiple parameters

⚠️ Warning: Unknown route parameters in Laravel will be appended as query strings with empty values.

Query parameters

Rzl Ziggy adds arguments that don't match any named route parameters as query parameters:

If you need to pass a query parameter with the same name as a route parameter, nest it under the special _query key:

Like Laravel, Rzl Ziggy automatically encodes boolean query parameters as integers in the query string:

• Usage at JS/TS example:

Examples

HTTP request with axios:

⚠️ Warning: Calling route() Without Arguments

• Calling route() without a name (or with undefined / null) can cause runtime errors when used in a string context.

  ❌ Incorrect usage:

  These patterns may throw an error, such as:

  ℹ️ The actual error message may vary depending on your environment or build process, but it typically happens because route() without a name returns an object that can't be coerced to a string.

  ✅ Correct usage:

  💡 To safely introspect the current route, use route() as an object:

  • route().current()
  • route().has('route.name')
  • route().params
  • route().queryParams
  • route().routeParams

Router class

Calling Rzl Ziggy's route() function with no arguments will return an instance of its JavaScript Router class, which has some other useful properties and methods.

Check the current route: route().current()

route().current(...) optionally accepts parameters as its second argument, and will check that their values also match in the current URL:

Check if a route exists: route().has(...)

Retrieve the current route params: route().params

Note: parameter values retrieved with route().params will always be returned as strings or undefined.

Retrieve only params route in laravel route (except query search params) in the current route: route().routeParams

Note: parameter values retrieved with route().routeParams will always be returned as strings or undefined.

Retrieve all search query params only (except params route in laravel route) in the current route: route().queryParams

Note: parameter values retrieved with route().queryParams will always be returned as strings or undefined.

Route-model binding

Rzl Ziggy supports Laravel's route-model binding, and can even recognize custom route key names. If you pass route() a JavaScript object as a route parameter, Rzl Ziggy will use the registered route-model binding keys for that route to find the correct parameter value inside the object. If no route-model binding keys are explicitly registered for a parameter, Rzl Ziggy will use the object's id key.

Rzl Ziggy also supports custom keys for scoped bindings declared directly in a route definition:

TypeScript Support

Rzl Ziggy includes TypeScript type definitions, and an Artisan command that can generate additional type definitions to enable route name and parameter autocompletion.

To generate route types, run the rzl-ziggy:generate command with the --types or --types-only option:

To make your IDE aware that Rzl Ziggy's route() helper is available globally, and to type it correctly, add a declaration like this in a .d.ts file somewhere in your project:

If you don't have Rzl Ziggy's NPM package installed, add the following to your jsconfig.json or tsconfig.json to load Rzl Ziggy's types from your vendor directory:

JavaScript frameworks

[!NOTE] Many applications don't need the additional setup described here—the @rzlRoutes Blade directive makes Rzl Ziggy's route() function and config available globally, including within bundled JavaScript files.

If you are not using the @rzlRoutes Blade directive, you can import Rzl Ziggy's route() function and configuration directly into JavaScript/TypeScript files.

Generating and importing Rzl Ziggy's configuration

Rzl Ziggy provides an Artisan command to output its config and routes to a file:

This command places your configuration in resources/js/rzl-ziggy/routes/index.ts by default, but you can customize this path by passing an argument to the Artisan command or setting in the laravel config file rzl-ziggy.output.path.main for name file Using JavaScript or TypeScript.

The file rzl-ziggy:generate creates looks something like this:

For TypeScript:

For JavaScript:

Importing the route() function

You can import Rzl Ziggy like any other JavaScript library.
However, without the @rzlRoutes Blade directive, the route config (typically named appRoutes) is not available globally.

This means:

• You must manually pass the config to the route() function.
• Since appRoutes is a string, you need to parse it using JSON.parse() before passing it in.

ℹ️ Path import import { appRoutes } from './rzl-ziggy/routes/index.js'; depend from your setting at config php file, see: Output Name File And Path To Generate.

To simplify importing the route() function, you can create an alias to the vendor path:

Now your imports can be shortened to:

Vue

Rzl Ziggy includes a Vue plugin to make it easy to use the route() helper throughout your Vue app:

Now you can use the route() function anywhere in your Vue components and templates:

With <script setup> in Vue 3 you can use inject to make the route() function available in your component script:

If you are not using the @rzlRoutes Blade directive, import Rzl Ziggy's configuration too and pass it to .use():

ℹ️ Path import import { appRoutes } from './rzl-ziggy/routes/index.js'; depend from your setting at config php file, see: Output Name File And Path To Generate.

If you're using TypeScript, you may need to add the following declaration to a .d.ts file in your project to avoid type errors when using the route() function in your Vue component templates:

React

Rzl Ziggy includes a useRoute() hook to make it easy to use the route() helper in your React app:

If you are not using the @rzlRoutes Blade directive, import Rzl Ziggy's configuration too and pass it to useRoute():

ℹ️ Path import import { appRoutes } from './rzl-ziggy/routes/index.js'; depend from your setting at config php file, see: Output Name File And Path To Generate.

You can also make the Rzl Ziggy config object available globally, so you can call useRoute() without passing Rzl Ziggy's configuration to it every time:

SPAs or separate repos

Rzl Ziggy's route() function is available as an NPM package, for use in JavaScript projects managed separately from their Laravel backend (i.e. without Composer or a vendor directory). You can install the NPM package with npm install rzl-app-ziggy.

To make your routes available on the frontend for this function to use, you can either run php artisan rzl-ziggy:generate and add the generated config file to your frontend project, or you can return Rzl Ziggy's config as JSON from an endpoint in your Laravel API (see Retrieving Rzl Ziggy's config from an API endpoint below for an example of how to set this up).

Publish Config File

You can customize the default configuration of Rzl Ziggy by publishing the rzl-ziggy.php file to your config directory. Run the following command in your terminal:

Filtering Routes

Rzl Ziggy supports filtering the list of routes it outputs, which is useful if you have certain routes that you don't want to be included and visible in your HTML source.

[!IMPORTANT] Hiding routes from Rzl Ziggy's output is not a replacement for thorough authentication and authorization. Routes that should not be accessibly publicly should be protected by authentication whether they're filtered out of Rzl Ziggy's output or not.

Including/excluding routes

To set up route filtering, create a config file in your Laravel app at config/rzl-ziggy.php and add either an only or except key containing an array of route name patterns.

Note: You have to choose one or the other. Setting both only and except will disable filtering altogether and return all named routes.

You can use asterisks as wildcards in route filters. In the example below, admin.* will exclude routes named admin.login, admin.register, etc.:

Filtering with groups

You can also define groups of routes that you want make available in different places in your app, using a groups key in your config file:

Then, you can expose a specific group by passing the group name into the @rzlRoutes Blade directive:

To expose multiple groups you can pass an array of group names:

Note: Passing group names to the @rzlRoutes directive will always take precedence over your other only or except settings.

Default Parameter Values

Rzl Ziggy supports default route parameter values (Laravel docs).

With config file:

ℹ️ To generate config file, see: Publish Config File.

Routes File Generator

Using JavaScript or TypeScript

You can also format your front-end using JavaScript or TypeScript when running the Artisan commands php artisan rzl-ziggy:generate or php artisan rzl-ziggy:generate --types:

⚠️ Valid options: "ts" (TypeScript, .ts), "js" (JavaScript, .js) ,default: "ts".

ℹ️ Notes:

• If this config value (rzl-ziggy.lang) is invalid or empty, it defaults to "ts".
• You can override it using the CLI option: php artisan rzl-ziggy:generate --lang=....
• If the CLI --lang value is invalid, it falls back to this config value.
• If both are invalid, "ts" will be used as a safe fallback.

Output Name File And Path To Generate

You can also set the output location when running the Artisan command php artisan rzl-ziggy:generate or php artisan rzl-ziggy:generate --types:

⚠️ Be careful when naming the folder and file: if the folder name and filename are the same (e.g. folder routes/ and file routes.ts), a file with the same name inside the folder may be accidentally overwritten.

ℹ️ The "output.name" is name of the generated route file (without extension).
Example: "index" will become index.ts or index.js depending on the selected lang.

Notes:  
- The extension will be automatically added based on the `lang` value (`"ts"` or `"js"`).  
- If this value is invalid or empty, it defaults to `"index"`.  
- You can override this config using the CLI option: `--name=...`.  
- If both are invalid, `"index"` will be used as the safe default.

ℹ️ The "output.path.main" is output folder path for the main generated route file.
Example: "resources/js/rzl-ziggy/routes" will result in something like "resources/js/rzl-ziggy/routes/index.ts"

Notes:  
- Do **not** prefix the path with `/` or `\\` — it should be relative to the project root.  
- This path can be overridden using the CLI option: `--path=...`  
- If the CLI `--path` is null, empty, or omitted, and this config value is also empty or invalid, it will default to: `"resources/js/rzl-ziggy/routes"`.  
- If the provided path is invalid (e.g. not writable or not a directory), an error will be thrown.  
- This path does **not** include the filename or extension — only the folder.

---

Automatically Regenerates File Routes

Rzl Ziggy includes a built-in Vite plugin that automatically generates a route index file (index.ts or index.js) based on your Laravel named routes (location depends your setting, see: Output Name File And Path To Generate).

- Works the same as:

- Auto-regenerates the file whenever:

- You change `.env` (e.g. APP_URL).
- You update any `routes/*.php` file.
- You change on `config/rzl-ziggy.php` file.
- No need to run manual commands—works live in development (npm run dev).

- Setting in your vite.config.ts or vite.config.js, register the plugin:

Other

TLS/SSL termination and trusted proxies

If your application is using TLS/SSL termination or is behind a load balancer or proxy, or if it's hosted on a service that is, Rzl Ziggy may generate URLs with a scheme of http instead of https, even if your app URL uses https. To fix this, set up your Laravel app's trusted proxies according to the documentation on Configuring Trusted Proxies.

Using @rzlRoutes with a Content Security Policy

A Content Security Policy (CSP) may block inline scripts, including those output by Rzl Ziggy's @rzlRoutes Blade directive. If you have a CSP and are using a nonce to flag safe inline scripts, you can pass the nonce to the @rzlRoutes directive and it will be added to Rzl Ziggy's script tag:

Disabling the route() helper

If you only want to use the @rzlRoutes directive to make Rzl Ziggy's configuration available in JavaScript, but don't need the route() helper function, set the rzl-ziggy.skip-route-function config to true.

Retrieving Rzl Ziggy's config from an API endpoint

If you need to retrieve Rzl Ziggy's config from your Laravel backend over the network, you can create a route that looks something like this:

Contributing

This project is heavily inspired by and based on Ziggy, originally developed by the team at Tighten.

Original Authors of Ziggy:

• Daniel Coulbourne
• Jake Bathman
• Matt Stauffer
• Jacob Baker-Kretzmar
• All contributors

Additional Customization by:

• Rzl App

Special thanks to Caleb Porzio, Adam Wathan, and Jeffrey Way for help solidifying the idea.

Security

Please review our security policy on how to report security vulnerabilities.

License

Rzl Ziggy is open-source software released under the MIT license. See LICENSE for more information.

Credits

• Forked and extended from Ziggy by Tighten.
• Inspired by the work of Daniel Coulbourne, Jake Bathman, Matt Stauffer, and Jacob Baker-Kretzmar.
• Custom features and enhancements maintained by Rizalfin Dwiky (RZL)