Configuration

Configure Ziggy route filtering, groups, and output options

Ziggy can be configured using a config/ziggy.php file in your Laravel application. All configuration options are optional.

Creating the Config File

Create a configuration file at config/ziggy.php:

<?php

return [
    // Your configuration options
];

Configuration Options

only

Include only routes matching the specified patterns.

only · array

Array of route name patterns to include. Supports wildcards (*).

return [
    'only' => ['home', 'posts.*', 'users.show'],
];

Only these routes will be available to Ziggy’s JavaScript.

You cannot use both only and except at the same time. If both are set, Ziggy will ignore both and include all routes.

Example:

// Only include public-facing routes
return [
    'only' => [
        'home',
        'about',
        'contact',
        'posts.*',
        'users.show',
    ],
];

except

Exclude routes matching the specified patterns.

except · array

Array of route name patterns to exclude. Supports wildcards (*).

return [
    'except' => ['_debugbar.*', 'horizon.*', 'admin.*'],
];

These routes will be hidden from Ziggy’s JavaScript output.

Example:

// Exclude internal and admin routes
return [
    'except' => [
        '_debugbar.*',
        'horizon.*',
        'telescope.*',
        'admin.*',
        'api.internal.*',
    ],
];

groups

Define named groups of routes that can be loaded selectively.

groups · array

Array of group names, each containing an array of route patterns.

return [
    'groups' => [
        'admin' => ['admin.*', 'users.*'],
        'public' => ['home', 'posts.*', 'about'],
        'api' => ['api.*'],
    ],
];

Example:

return [
    'groups' => [
        // Admin panel routes
        'admin' => [
            'admin.*',
            'users.*',
            'settings.*',
        ],
        
        // Public website routes
        'public' => [
            'home',
            'about',
            'contact',
            'posts.*',
            'users.show',
        ],
        
        // API routes
        'api' => [
            'api.v1.*',
            'api.v2.*',
        ],
        
        // Author dashboard
        'author' => [
            'posts.*',
            'drafts.*',
            'profile.*',
        ],
    ],
];

Usage:

{{-- Load a specific group --}}
@routes('admin')

{{-- Load multiple groups --}}
@routes(['public', 'api'])

# Generate file for a specific group
php artisan ziggy:generate --group=admin

middleware

Include route middleware in Ziggy’s output.

middleware · boolean|array

Control middleware inclusion:

• false (default): Don’t include middleware
• true: Include all middleware
• array: Include only specified middleware

return [
    // Include all middleware
    'middleware' => true,
    
    // Include only specific middleware
    'middleware' => ['auth', 'verified', 'admin'],
];

Example:

// Include authentication-related middleware
return [
    'middleware' => ['auth', 'verified', 'guest'],
];

Output:

const Ziggy = {
    routes: {
        'posts.create': {
            uri: 'posts/create',
            methods: ['GET', 'HEAD'],
            middleware: ['auth', 'verified']
        }
    }
};

output

Customize output paths and classes for generated files.

output · array

Configure output behavior for different Ziggy features.

output.path

output.path · string · default: "resources/js/ziggy.js"

Default output path for php artisan ziggy:generate.

return [
    'output' => [
        'path' => 'resources/js/routes.js',
    ],
];

output.types-path

output.types-path · string · default: "resources/js/ziggy.d.ts"

Default output path for TypeScript definitions.

return [
    'output' => [
        'types-path' => 'resources/types/ziggy.d.ts',
    ],
];

output.file

output.file · string · default: "\\Tighten\\Ziggy\\Output\\File"

Custom class for generating JavaScript files.

return [
    'output' => [
        'file' => \App\Ziggy\CustomFileOutput::class,
    ],
];

output.types

output.types · string · default: "\\Tighten\\Ziggy\\Output\\Types"

Custom class for generating TypeScript declarations.

return [
    'output' => [
        'types' => \App\Ziggy\CustomTypesOutput::class,
    ],
];

output.script

output.script · string · default: "\\Tighten\\Ziggy\\Output\\Script"

Custom class for @routes Blade directive output.

return [
    'output' => [
        'script' => \App\Ziggy\CustomScriptOutput::class,
    ],
];

output.json

output.json · string · default: "\\Tighten\\Ziggy\\Output\\Json"

Custom class for JSON output (when using @routes(json: true)).

return [
    'output' => [
        'json' => \App\Ziggy\CustomJsonOutput::class,
    ],
];

output.merge_script

output.merge_script · string · default: "\\Tighten\\Ziggy\\Output\\MergeScript"

Custom class for subsequent @routes calls on the same page.

return [
    'output' => [
        'merge_script' => \App\Ziggy\CustomMergeOutput::class,
    ],
];

Complete output configuration:

return [
    'output' => [
        'path' => 'resources/js/routes.js',
        'types-path' => 'resources/types/routes.d.ts',
        'file' => \Tighten\Ziggy\Output\File::class,
        'types' => \Tighten\Ziggy\Output\Types::class,
        'script' => \Tighten\Ziggy\Output\Script::class,
        'json' => \Tighten\Ziggy\Output\Json::class,
        'merge_script' => \Tighten\Ziggy\Output\MergeScript::class,
    ],
];

skip-route-function

Disable the route helper function in @routes output.

skip-route-function · boolean · default: false

When true, the @routes directive only outputs route configuration (no route() function).

return [
    'skip-route-function' => true,
];

Useful when importing the route function separately from the NPM package.

Example:

return [
    'skip-route-function' => true,
];

With this setting, @routes outputs:

<script>
const Ziggy = { /* routes config */ };
// No route() function included
</script>

You’ll need to import route() separately:

import { route } from 'ziggy-js';

Complete Example

Here’s a comprehensive configuration example:

<?php
// config/ziggy.php

return [
    // Exclude internal routes
    'except' => [
        '_debugbar.*',
        'horizon.*',
        'telescope.*',
        'sanctum.*',
    ],
    
    // Define route groups
    'groups' => [
        'admin' => [
            'admin.*',
            'users.*',
            'settings.*',
        ],
        'public' => [
            'home',
            'about',
            'contact',
            'posts.*',
            'users.show',
        ],
        'api' => [
            'api.v1.*',
        ],
    ],
    
    // Include auth middleware in output
    'middleware' => ['auth', 'verified'],
    
    // Customize output
    'output' => [
        'path' => 'resources/js/ziggy.js',
        'types-path' => 'resources/js/ziggy.d.ts',
    ],
];

Common Configurations

Secure Configuration (Hide Admin Routes)

return [
    'except' => [
        'admin.*',
        '_debugbar.*',
        'horizon.*',
        'telescope.*',
    ],
];

API-Only Configuration

return [
    'only' => ['api.*'],
    'middleware' => ['auth:sanctum', 'throttle'],
];

Multi-Tenant Configuration

return [
    'groups' => [
        'tenant' => ['tenant.*'],
        'landlord' => ['landlord.*'],
        'shared' => ['home', 'profile.*'],
    ],
];

SPA Configuration

return [
    'output' => [
        'path' => 'resources/js/ziggy.js',
        'types-path' => 'resources/js/ziggy.d.ts',
    ],
    'skip-route-function' => true,
];

Security Considerations

Hiding routes from Ziggy’s output is not a security measure. Always protect your routes with proper authentication and authorization, regardless of whether they appear in Ziggy’s configuration.

Best practices:

1. Use route filtering to keep your JavaScript bundle smaller and reduce information exposure
2. Always implement authentication/authorization on your routes
3. Don’t rely on obscurity - assume all route names are public
4. Use groups to load only necessary routes on each page

// Good: Filter + protect routes
return [
    'except' => ['admin.*'],
];

// Route protection is still required!
Route::middleware(['auth', 'admin'])->group(function () {
    Route::get('admin/dashboard', ...)->name('admin.dashboard');
});

Related

Blade Directive

Use @routes with configured groups and filters

Artisan Commands

Generate files with configured paths

Ziggy Class

Understand how configuration affects the Ziggy class