Ziggy Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tightenco/ziggy
   

2. Add Blade Directive: Place @routes in your main layout file (e.g., resources/views/layouts/app.blade.php) before your JavaScript bundles:

   @routes
   @vite(['resources/js/app.js'])
   

3. First Use Case: Use the route() function in JavaScript like Laravel’s PHP helper:

   // Generate URL for a named route
   const url = route('posts.index'); // e.g., "/posts"
   

Implementation Patterns

Core Workflows

1. Route Generation:

   • Basic: route('route.name') → /uri.
   • With Parameters:

     route('posts.show', 1); // "/posts/1"
     route('posts.show', { post: 1 }); // Same as above
     

   • Query Strings:

     route('posts.index', { page: 2 }); // "/posts?page=2"
     route('posts.show', { post: 1, _query: { sort: 'new' } }); // "/posts/1?sort=new"
     

2. Framework Integration:

   • Vue: Use ZiggyVue plugin for global route() access:

     import { createApp } from 'vue';
     import { ZiggyVue } from 'ziggy-js';
     createApp(App).use(ZiggyVue);
     

     Access in templates:

     <a :href="route('home')">Home</a>
     

   • React: Use useRoute() hook:

     const route = useRoute();
     <a href={route('dashboard')}>Dashboard</a>
     

3. SPA/Static Sites:

   • Generate routes via CLI:

     php artisan ziggy:generate
     

   • Import manually in JS:

     import { route } from 'ziggy-js';
     import { Ziggy } from './ziggy.js';
     route('home', {}, {}, Ziggy);
     

4. TypeScript Support:

   • Generate types:

     php artisan ziggy:generate --types
     

   • Declare global route for autocompletion:

     declare global { var route: typeof import('ziggy-js').route; }
     

Gotchas and Tips

Pitfalls

1. Route Filtering:

   • By default, @routes includes all routes in HTML. Omit sensitive routes:

     Ziggy::routes(function () {
         return ['posts.*', 'auth.*']; // Only include these
     });
     

   • Use Ziggy::ignore() to exclude routes:

     Ziggy::ignore(['admin.*']);
     

2. Parameter Mismatches:

   • Ziggy throws errors if route parameters don’t match Laravel’s definitions. Validate in JS:

     if (!route().has('posts.show')) console.error('Route missing!');
     

3. Model Binding Quirks:

   • Custom getRouteKeyName() must match Laravel’s binding. Ziggy uses id by default:

     // Fails if Post uses `slug` but JS passes `id`
     route('posts.show', { id: 1 }); // "/posts/1" (not slug)
     

4. SPA Caching:

   • Regenerate ziggy.js after route changes:

     php artisan ziggy:generate --force
     

Debugging Tips

1. Inspect Routes:

   • Log all routes in JS:

     console.log(route().routes);
     

   • Check current route params:

     console.log(route().params); // { venue: "1", event: "2" }
     

2. TypeScript Strict Mode:

   • Enable strict route names to catch typos:

     declare module 'ziggy-js' {
       interface TypeConfig { strictRouteNames: true; }
     }
     

3. Query Parameter Conflicts:

   • Use _query to avoid overriding route params:

     route('posts.show', { post: 1, _query: { post: 'draft' } });
     // "/posts/1?post=draft" (not "/posts/draft")
     

4. Vue/React Edge Cases:

   • Ensure ZiggyVue/useRoute is initialized before components mount.
   • For SSR, exclude @routes from server-side rendering (use client-side only).

Extension Points

1. Custom Route Metadata:

   • Extend Ziggy’s config to include extra data (e.g., permissions):

     Ziggy::with(['auth' => auth()->check()]);
     

     Access in JS:

     if (Ziggy.auth) { /* ... */ }
     

2. Dynamic Route Prefixes:

   • Override Ziggy.url in JS for multi-tenant apps:

     route('home', {}, {}, { ...Ziggy, url: 'https://tenant1.app' });
     

3. Webpack/Vite Aliases:

   • Simplify imports with path aliases:

     // vite.config.js
     resolve: { alias: { 'ziggy-js': '/vendor/tightenco/ziggy' } }