vite-plugin-ziggy

0.3.0 verified Mon Apr 27 auth: no javascript

Vite plugin that auto-generates TypeScript route type definitions for Laravel Ziggy based on your Laravel route files. Current stable version is 0.3.0, released with a focus on seamless integration with Laravel development workflows. Key differentiators: automatic regeneration on route file changes, support for Sail, route filtering (only/except), and optional sail/php execution. Alternatives require manual type generation or separate build steps.

Common errors

error Cannot find module 'vite-plugin-ziggy/routes' or its corresponding type declarations. ↓

cause TypeScript cannot locate generated type declaration because tsconfig.json 'types' array is missing.

fix

Add "vite-plugin-ziggy/routes" to the 'types' array in tsconfig.json.

error TypeError: ziggy is not a function ↓

cause Incorrect import style: using named export instead of default export.

fix

Use default import: import ziggy from 'vite-plugin-ziggy';

error The term 'sail' is not recognized as the name of a cmdlet, function, script file, or operable program. ↓

cause Sail option enabled but Laravel Sail is not installed or not in PATH.

fix

Disable sail: false or install Laravel Sail.

Warnings

gotcha Generated types file is placed in node_modules; ensure it's not committed to version control. ↓

fix Add node_modules/vite-plugin-ziggy/routes.d.ts to .gitignore.

gotcha ZiggyRoute type is declared globally; conflicts with other packages using same global name may occur. ↓

fix Rename global type using plugin config or avoid duplicate global names.

breaking v1.0.0 will change default output path from node_modules/vite-plugin-ziggy/routes to a project-level location. ↓

fix Set custom path in plugin configuration to prepare for migration.

deprecated Option 'typesOnly' defaults to true but in v0.4.0 will default to false to generate both types and actual route data. ↓

fix Explicitly set typesOnly: false if you need both types and route data.

gotcha Requires Laravel project with artisan route:list command accessible. Sail option uses 'sail' shell command. ↓

fix Ensure 'php artisan' or 'sail' is available in PATH.

Install

npm install vite-plugin-ziggy

yarn add vite-plugin-ziggy

pnpm add vite-plugin-ziggy

Imports

default (ziggy)
wrong
```
const ziggy = require('vite-plugin-ziggy');
```
correct
```
import ziggy from 'vite-plugin-ziggy';
```
Default export; ESM-only usage recommended in Vite config files. CommonJS require works in CJS contexts, but Vite configs are typically ESM.
type declaration
wrong
```
import './node_modules/vite-plugin-ziggy/routes';
```
correct
```
// In tsconfig.json types: ["vite-plugin-ziggy/routes"]
```
Add to tsconfig.json types array, not import statement. This references the generated type declaration file at node_modules/vite-plugin-ziggy/routes.
ZiggyRoute type
wrong
```
import { ZiggyRoute } from 'vite-plugin-ziggy';
```
correct
```
// Generated type is available globally as ZiggyRoute
```
ZiggyRoute is declared globally in the generated types file. Do not import from the package directly.

Quickstart

Shows minimal Vite plugin setup with common options and tsconfig type inclusion for generated route types.

// vite.config.ts
import { defineConfig } from 'vite';
import ziggy from 'vite-plugin-ziggy';

export default defineConfig({
  plugins: [
    ziggy({
      sail: true,
      group: 'api',
      url: process.env.APP_URL ?? 'http://localhost',
      only: ['admin.*'],
      except: ['debugbar.*'],
      types: true,
      typesOnly: false,
    }),
  ],
});

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vite/client", "vite-plugin-ziggy/routes"]
  }
}

// After running vite, route types are auto-generated.
// Use in any TS file:
const routeName: ZiggyRoute = 'admin.users.index';
route(routeName, { id: 1 }); // typed parameters