Skip to main content

​
Installation

Ziggy can be installed in any Laravel application using Composer. For SPAs or applications with separate frontend repositories, you can also install the NPM package.

​
Requirements

  • PHP: 8.1 or higher
  • Laravel: 9.0 or higher
  • JSON extension: Required for PHP

​
Composer Installation

Install Ziggy via Composer in your Laravel application: 
composer require tightenco/ziggy
Ziggy uses Laravel’s package auto-discovery, so the service provider will be automatically registered.
No additional configuration is required. Ziggy is ready to use immediately after installation.

​
NPM Installation (Optional)

For applications using JavaScript bundlers like Vite or Webpack, you can optionally install Ziggy’s NPM package: 
npm install ziggy-js
The NPM package is optional for most Laravel applications. You only need it if you’re:
  • Building an SPA with a separate frontend repository
  • Not using the @routes Blade directive
  • Importing Ziggy directly in JavaScript modules

​
Basic Setup

​
Adding the @routes Directive

The simplest way to use Ziggy is to add the @routes Blade directive to your main layout file. This makes the route() function available globally in your JavaScript. Add the directive in your layout’s <head> section, before your application’s JavaScript: 
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{{ config('app.name') }}</title>
    
    <!-- Ziggy Routes -->
    @routes
    
    <!-- Your app's JavaScript -->
    @vite(['resources/js/app.js'])
</head>
<body>
    @yield('content')
</body>
</html>
The @routes directive must be placed before your JavaScript files to ensure the route configuration is available when your scripts load.

​
What @routes Does

The @routes directive outputs:
  1. Your application’s base URL and configuration
  2. A list of all named routes with their URIs, methods, and parameters
  3. The Ziggy JavaScript route() helper function
Example output: 
<script>
    const Ziggy = {
        url: 'https://ziggy.test',
        port: null,
        defaults: {},
        routes: {
            'posts.index': {
                uri: 'posts',
                methods: ['GET', 'HEAD'],
            },
            'posts.show': {
                uri: 'posts/{post}',
                methods: ['GET', 'HEAD'],
                parameters: ['post'],
                bindings: { post: 'id' }
            }
        }
    };
    
    // Ziggy's route() helper function
    // ...
</script>

​
Verifying Installation

1

Create a Test Route

Add a simple named route to your routes/web.php:
Route::get('/test', function () {
    return 'Ziggy test route';
})->name('test');
2

Use route() in JavaScript

Open your browser’s console on any page and test the route() function:
route('test'); // Should output: 'https://your-app.test/test'
3

Check Available Routes

List all available routes:
route().has('test'); // Should return: true
Object.keys(Ziggy.routes); // Shows all your route names
If route('test') returns a URL, Ziggy is installed correctly!

​
Configuration (Optional)

Ziggy works out of the box without any configuration. However, you can customize its behavior by publishing the configuration file: 
php artisan vendor:publish --tag=ziggy-config
This creates a config/ziggy.php file with the following options:
config/ziggy.php
<?php

return [
    // Only include specific routes
    'only' => [],
    
    // Exclude specific routes (cannot be used with 'only')
    'except' => [],
    
    // Define named groups of routes
    'groups' => [
        'admin' => ['admin.*'],
        'public' => ['home', 'posts.*', 'about'],
    ],
    
    // Output file path for 'ziggy:generate' command
    'output' => [
        'path' => 'resources/js/ziggy.js',
    ],
];
only: Array of route patterns to include (e.g., ['posts.*', 'users.show'])except: Array of route patterns to exclude (e.g., ['admin.*', '_debugbar.*'])groups: Named groups of routes that can be included on specific pagesoutput.path: Where to generate the routes file when using php artisan ziggy:generate

​
Alternative Setup Methods

​
For JavaScript Frameworks (Vue, React)

If you’re building an SPA or prefer to import Ziggy in your JavaScript modules:
1

Generate the Routes File

Run the Artisan command to generate a JavaScript routes file:
php artisan ziggy:generate
This creates resources/js/ziggy.js with your route configuration.
2

Import in Your JavaScript

import { createApp } from 'vue';
import { ZiggyVue } from 'ziggy-js';
import { Ziggy } from './ziggy';

const app = createApp({});
app.use(ZiggyVue, Ziggy);

​
For SPAs or Separate Repositories

If your frontend is completely separate from your Laravel backend:
1

Install NPM Package

npm install ziggy-js
2

Generate Routes File

Run the command in your Laravel app:
php artisan ziggy:generate resources/js/ziggy.js
Copy the generated file to your frontend project.
3

Or Create API Endpoint

Alternatively, create an API endpoint to fetch routes:
routes/api.php
use Tighten\Ziggy\Ziggy;

Route::get('/api/ziggy', fn () => response()->json(new Ziggy));

​
TypeScript Support

Ziggy includes TypeScript type definitions. To enable route name autocompletion: 
php artisan ziggy:generate --types
This generates type definitions for all your routes. Add this to a .d.ts file:
types/ziggy.d.ts
import { route as routeFn } from 'ziggy-js';

declare global {
    var route: typeof routeFn;
}

​
Next Steps

Quickstart Guide

Build your first Ziggy-powered feature in minutes

Usage Examples

Learn all the ways to use the route() function

Build docs developers (and LLMs) love

Get started for freeTalk to us