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

yarn add ziggy-js

pnpm add 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>

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    
    @routes
    @vite(['resources/js/app.js'])
    @inertiaHead
</head>
<body>
    @inertia
</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:

Your application’s base URL and configuration
A list of all named routes with their URIs, methods, and parameters
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

Create a Test Route

Add a simple named route to your routes/web.php:

Route::get('/test', function () {
    return 'Ziggy test route';
})->name('test');

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'

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',
    ],
];

Configuration Options Explained

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:

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.

Import in Your JavaScript

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

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

import { useRoute } from 'ziggy-js';
import { Ziggy } from './ziggy';

function MyComponent() {
    const route = useRoute(Ziggy);
    return <a href={route('posts.index')}>Posts</a>;
}

For SPAs or Separate Repositories

If your frontend is completely separate from your Laravel backend:

Install NPM Package

npm install ziggy-js

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.

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;
}

Get Started

Core Concepts

Framework Integration

Advanced Usage

Guides

Installation

Installation

Requirements

Composer Installation

NPM Installation (Optional)

Basic Setup

Adding the @routes Directive

What @routes Does

Verifying Installation

Configuration (Optional)

Alternative Setup Methods

For JavaScript Frameworks (Vue, React)

For SPAs or Separate Repositories

TypeScript Support

Next Steps

Quickstart Guide

Usage Examples

​Installation

​Requirements

​Composer Installation

​NPM Installation (Optional)

​Basic Setup

​Adding the @routes Directive

​What @routes Does

​Verifying Installation

​Configuration (Optional)

​Alternative Setup Methods

​For JavaScript Frameworks (Vue, React)

​For SPAs or Separate Repositories

​TypeScript Support

​Next Steps

Quickstart Guide

Usage Examples

Installation

Requirements

Composer Installation

NPM Installation (Optional)

Basic Setup

Adding the @routes Directive

What @routes Does

Verifying Installation

Configuration (Optional)

Alternative Setup Methods

For JavaScript Frameworks (Vue, React)

For SPAs or Separate Repositories

TypeScript Support

Next Steps