Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default (ziggy)
✓ import ziggy from 'vite-plugin-ziggy';
✗ const ziggy = require('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
✓ // In tsconfig.json types: ["vite-plugin-ziggy/routes"]
✗ import './node_modules/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
✓ // Generated type is available globally as ZiggyRoute
✗ import { ZiggyRoute } from 'vite-plugin-ziggy';
ZiggyRoute is declared globally in the generated types file. Do not import from the package directly.
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
Errors
Common errors & fixes
Cannot find module 'vite-plugin-ziggy/routes' or its corresponding type declarations.
TypeScript cannot locate generated type declaration because tsconfig.json 'types' array is missing.
fixAdd "vite-plugin-ziggy/routes" to the 'types' array in tsconfig.json.
TypeError: ziggy is not a function
Incorrect import style: using named export instead of default export.
fixUse default import: import ziggy from 'vite-plugin-ziggy';
The term 'sail' is not recognized as the name of a cmdlet, function, script file, or operable program.
Sail option enabled but Laravel Sail is not installed or not in PATH.
fixDisable sail: false or install Laravel Sail.
Audit
Dependencies
viterequiredVite plugin, requires Vite as peer dependency