> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/tighten/ziggy/llms.txt
> Use this file to discover all available pages before exploring further.
# Installation
> Install Ziggy in your Laravel application and start using your routes in JavaScript.
# 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:
```bash theme={null}
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:
```bash npm theme={null}
npm install ziggy-js
```
```bash yarn theme={null}
yarn add ziggy-js
```
```bash pnpm theme={null}
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 `` section, **before** your application's JavaScript:
```blade resources/views/layouts/app.blade.php theme={null}
{{ config('app.name') }}
@routes
@vite(['resources/js/app.js'])
@yield('content')
```
```blade resources/views/app.blade.php (Inertia) theme={null}
@routes
@vite(['resources/js/app.js'])
@inertiaHead
@inertia
```
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:
```html theme={null}
```
## Verifying Installation
Add a simple named route to your `routes/web.php`:
```php theme={null}
Route::get('/test', function () {
return 'Ziggy test route';
})->name('test');
```
Open your browser's console on any page and test the `route()` function:
```js theme={null}
route('test'); // Should output: 'https://your-app.test/test'
```
List all available routes:
```js theme={null}
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:
```bash theme={null}
php artisan vendor:publish --tag=ziggy-config
```
This creates a `config/ziggy.php` file with the following options:
```php config/ziggy.php theme={null}
[],
// 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 pages
**`output.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:
Run the Artisan command to generate a JavaScript routes file:
```bash theme={null}
php artisan ziggy:generate
```
This creates `resources/js/ziggy.js` with your route configuration.
```js Vue theme={null}
import { createApp } from 'vue';
import { ZiggyVue } from 'ziggy-js';
import { Ziggy } from './ziggy';
const app = createApp({});
app.use(ZiggyVue, Ziggy);
```
```jsx React theme={null}
import { useRoute } from 'ziggy-js';
import { Ziggy } from './ziggy';
function MyComponent() {
const route = useRoute(Ziggy);
return Posts;
}
```
### For SPAs or Separate Repositories
If your frontend is completely separate from your Laravel backend:
```bash theme={null}
npm install ziggy-js
```
Run the command in your Laravel app:
```bash theme={null}
php artisan ziggy:generate resources/js/ziggy.js
```
Copy the generated file to your frontend project.
Alternatively, create an API endpoint to fetch routes:
```php routes/api.php theme={null}
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:
```bash theme={null}
php artisan ziggy:generate --types
```
This generates type definitions for all your routes. Add this to a `.d.ts` file:
```ts types/ziggy.d.ts theme={null}
import { route as routeFn } from 'ziggy-js';
declare global {
var route: typeof routeFn;
}
```
## Next Steps
Build your first Ziggy-powered feature in minutes
Learn all the ways to use the route() function