ziggy-js

library2.6.2jsnpmunverified

Ziggy provides a JavaScript `route()` function that seamlessly integrates with Laravel's named routes, enabling consistent URL generation in frontend applications. The current stable version is 2.6.2, and the package maintains an active release cadence with frequent patch and minor updates, reflecting ongoing development and support. Its core differentiator lies in its ability to dynamically expose Laravel's PHP-defined routes to the JavaScript environment via a Blade directive, eliminating the need to hardcode URLs or duplicate routing logic. This integration includes support for advanced Laravel features such as route-model binding, automatic handling of query parameters, and robust TypeScript definitions for a type-safe development experience. Ziggy aims to simplify the development of single-page applications (SPAs) and traditional frontend projects by ensuring that frontend routing logic remains synchronized with the backend.

web-framework

npm install ziggy-js

github ↗package ↗

INSTALL

IMPORT

SIG · ZIGGY-JS

ziggy-js

web-frameworkjavascriptv2.6.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

route

✓ import { route } from 'ziggy-js';

✗ const { route } = require('ziggy-js');

The primary function to generate URLs. For global usage when using the Blade directive, it's often available directly as `route()` without explicit import. Using CommonJS `require` can lead to issues with module resolution or runtime errors in modern environments.

Router

✓ import { Router } from 'ziggy-js';

✗ const Router = require('ziggy-js').Router;

The `Router` class provides more advanced control over route generation and manipulation, particularly useful for custom setups or testing. Stick to named imports for ESM compatibility.

ZiggyConfig

✓ import type { ZiggyConfig } from 'ziggy-js';

✗ import { ZiggyConfig } from 'ziggy-js';

This is a TypeScript type for the global Ziggy configuration object. It should be imported using `import type` for type-only imports, especially in environments where type imports are tree-shaken.

This quickstart demonstrates how to use Ziggy's `route()` function to generate URLs for Laravel named routes in JavaScript, including handling parameters, multiple parameters, query strings, and basic route model binding. It simulates the `window.Ziggy` global configuration that Laravel injects.

declare global { interface Window { Ziggy: { url: string; port: null | number; defaults: Record<string, any>; routes: Record<string, { uri: string; methods: string[]; bindings?: Record<string, string>; wheres?: Record<string, string>; }>; }; } } // Simulate Ziggy configuration typically injected by Laravel's @routes Blade directive window.Ziggy = { url: 'https://example.com', port: null, defaults: {}, routes: { 'home': { uri: '/', methods: ['GET', 'HEAD'] }, 'posts.index': { uri: 'posts', methods: ['GET', 'HEAD'] }, 'posts.show': { uri: 'posts/{post}', methods: ['GET', 'HEAD'], wheres: { post: '[^/]+' } }, 'users.profile': { uri: 'users/{user}', methods: ['GET', 'HEAD'], bindings: { user: 'id' }, wheres: { user: '[^/]+' } }, 'venues.events.show': { uri: 'venues/{venue}/events/{event}', methods: ['GET', 'HEAD'], wheres: { venue: '[^/]+', event: '[^/]+' } } } }; import { route } from 'ziggy-js'; // Basic usage console.log('Home route:', route('home').toString()); // Expected: https://example.com/ // With parameters console.log('Post show (ID 1):', route('posts.show', { post: 1 }).toString()); // Expected: https://example.com/posts/1 // Multiple parameters console.log('Venue 1 Event 2:', route('venues.events.show', { venue: 1, event: 2 }).toString()); // Expected: https://example.com/venues/1/events/2 // Parameters with query strings console.log('Post show with query:', route('posts.show', { post: 1, page: 2, sort: 'asc' }).toString()); // Expected: https://example.com/posts/1?page=2&sort=asc // Route model binding (since v2.6.0) const user = { id: 5, name: 'Alice' }; // Simulate a Laravel model object console.log('User profile (ID 5):', route('users.profile', user).toString()); // Expected: https://example.com/users/5 // Simplified current route check (route().current() typically uses window.location) const isCurrentRoute = (path: string, routeName: string, params: Record<string, any>) => { const generatedPath = route(routeName, params, false).relative(); // Get relative path return path === generatedPath; // Simple path match }; console.log(`Is '/posts/1' the current 'posts.show' route? ${isCurrentRoute('/posts/1', 'posts.show', { post: 1 })}`); // Expected: Is '/posts/1' the current 'posts.show' route? true

Debug

Known issues

gotchaBy default, the `@routes` Blade directive exposes all Laravel routes and their parameters to the frontend HTML. This can be a security concern if sensitive backend routes (e.g., admin panels, internal APIs) are inadvertently exposed. Review and filter routes carefully.

fix

Use the `except` or `only` options with the `@routes` Blade directive (e.g., `@routes(['only' => ['web.*']])`) or the `php artisan ziggy:generate` command to explicitly control which routes are published. Utilize route groups for more granular control.

affects: >=1.0

breakingIn v2.6.0, the internal `qs` library for query string parsing and serialization was replaced. While typically an internal change, it *could* subtly alter query string behavior for very specific edge cases if you were relying on particular `qs` encoding/decoding characteristics.

fix

Test your application's routes involving complex query parameters after upgrading to v2.6.0. Most common use cases should be unaffected, but review if you encounter unexpected URL structures.

affects: >=2.6.0

gotchaFor Single Page Applications (SPAs) or projects with separate frontend repositories, the `Ziggy` configuration must be explicitly generated and imported, as the `@routes` Blade directive will not automatically inject it.

fix

Run `php artisan ziggy:generate --json` to output the route configuration to a JSON file. Import this file into your frontend application and initialize Ziggy's `route()` function with it: `import { route } from 'ziggy-js'; import Ziggy from '@/ziggy.json'; route.setZiggy(Ziggy);`

affects: >=1.0

breakingSupport for Laravel's route model binding and interfaces was introduced in v2.6.0. Applications relying on route model binding to automatically resolve parameters based on model instances will not function correctly with Ziggy versions prior to 2.6.0.

fix

Upgrade Ziggy to version 2.6.0 or higher to leverage route model binding functionality in your JavaScript routes. Ensure your Laravel backend is also up-to-date to fully support model binding features.

affects: <2.6.0

Errors

Common errors & fixes

ReferenceError: route is not defined

The global `route()` function was not initialized because the `@routes` Blade directive was omitted or placed incorrectly.

fix

Ensure `@routes` is included in your main Blade layout file (e.g., `app.blade.php`) before any JavaScript that uses Ziggy, typically within the `<head>` or at the start of `<body>`.

TypeError: (0, ziggy_js_1.route) is not a function

This error often occurs when attempting to use a CommonJS `require()` statement or an incorrect named import syntax for `ziggy-js` in an environment expecting ES Modules.

fix

For ES Module environments, use `import { route } from 'ziggy-js';`. If using a bundler, ensure your configuration correctly handles ES Modules. If your project strictly uses CommonJS, consider transpilation or adjusting your build setup as `ziggy-js` is primarily designed for ESM.

The route [your.route.name] is not found.

The specified route name either does not exist in your Laravel application, was misspelled, or was filtered out when Ziggy's configuration was generated.

fix

Double-check the route name against your Laravel `web.php` or `api.php` files. Verify your `php artisan ziggy:generate` command or `@routes` Blade directive parameters (`except`, `only`, `group`) are not inadvertently excluding the required route.

Upgrade

Version history

2.6.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tighten/ziggy ↗

packagehttps://www.npmjs.com/package/ziggy-js ↗