Ziggy Laravel Package

Getting Started

1. Install Ziggy via Composer: composer require tightenco/ziggy.
2. Add @routes Blade directive (e.g., in your main layout) before your application’s JavaScript bundle—this exposes the globally available route() helper and config.
3. Begin using route() in JS exactly like Laravel’s PHP helper: route('posts.show', { id: 1 }).
4. For TypeScript: run php artisan ziggy:generate --types to generate route-specific type declarations, and declare var route: typeof routeFn globally if needed.

Implementation Patterns

• Blade-first apps: Use @routes + route() directly in Blade-templated JS—no manual imports needed.
• SPA/Module-based apps: Generate config with php artisan ziggy:generate, then import route and Ziggy from ziggy-js (alias in vite.config.js for cleaner imports).
• Framework integrations:
  • Vue: use(ZiggyVue) in app entry; inject route via inject('route') in <script setup>.
  • React: use useRoute() hook; optionally pass Ziggy config explicitly.
• Parameter passing:
  • Use objects for named params: route('posts.show', { post: 42 }).
  • Pass models directly: Ziggy auto-detects route key names (e.g., slug) and id fallback.
  • Query params go outside route params (or nest under _query to avoid collisions).
• Route filtering: Exclude sensitive or unnecessary routes via Ziggy::map() in config/ziggy.php, using only, except, or groups.

Gotchas and Tips

• @routes embeds all routes in HTML by default—audit exposure in production (e.g., avoid exposing admin routes).
• Route param values from route().params are always strings—convert id to Number() before API calls.
• route() with no arguments returns the Router instance—don’t accidentally call route().current() as a URL generator; use route() for URLs.
• When not using @routes, always pass Ziggy config to route() or framework helpers (e.g., useRoute(Ziggy) in React)—silent failures occur otherwise.
• TypeScript strictness: enable strictRouteNames: true via module augmentation to catch typos at compile time—but ensure type generation includes all expected routes.
• Dev mode quirk: if route names change (e.g., new middleware added), rerun ziggy:generate or restart dev server if watching isn’t triggering rebuilds.