Upgrading to v2

Migration guide for upgrading from Ziggy 1.x to 2.x

Ziggy 2.x includes several breaking changes. Please review this guide carefully before upgrading.

Requirements

Ziggy 2.x requires:

• Laravel 9 or higher
• PHP 8.1 or higher

Breaking Changes

Namespace Change

⚠️ Breaking Change: The PHP package namespace has changed from Tightenco\Ziggy to Tighten\Ziggy.

Note: The Composer package name (tightenco/ziggy) has not changed.

Before:

use Tightenco\Ziggy\Ziggy;

After:

use Tighten\Ziggy\Ziggy;

1. Update namespace imports

   Search your codebase for Tightenco\Ziggy and replace with Tighten\Ziggy.

2. Clear cached files

   Run php artisan config:clear and php artisan route:clear to clear any cached references.

JavaScript Module Changes

⚠️ Breaking Change: Ziggy’s JavaScript now provides named exports only, with no default export.

Before:

import route from 'ziggy-js';

After:

import { route } from 'ziggy-js';

Vue and React Import Changes

⚠️ Breaking Change: Ziggy’s Vue plugin and React hook have moved to the root of the module.

Before:

import { ZiggyVue } from 'ziggy-js/vue';
import { useRoute } from 'ziggy-js/react';

After:

import { route, ZiggyVue } from 'ziggy-js';
import { route, useRoute } from 'ziggy-js';

Build Changes

⚠️ Breaking Change: Ziggy now only includes ES Module builds.

Ziggy 2.x provides the following builds:

• Default build: ./dist/index.js - Supports all modern browsers (default when importing from ziggy-js or vendor/tightenco/ziggy)
• Legacy ES Module: ./dist/index.esm.js - Uses fewer new language features for broader compatibility
• UMD build: ./dist/route.umd.js - For internal use in Ziggy’s @routes Blade directive

If you were relying on a CommonJS build, you’ll need to update your build configuration to support ES modules.

Method Removal

⚠️ Breaking Change: The deprecated JavaScript check() method has been removed.

Before:

route().check('home');

After:

route().has('home');

PHP Internal Changes

⚠️ Breaking Change: The makeDirectory method of the CommandRouteGenerator class is now private.

Overriding this method is no longer supported. If you were extending this class and overriding makeDirectory, you’ll need to find an alternative approach.

Migration Steps

1. Update Composer dependencies

   Update your composer.json to ensure you’re running Laravel 9+ and PHP 8.1+:

   composer update tightenco/ziggy
   
2. Update PHP namespace imports

   Replace all instances of Tightenco\Ziggy with Tighten\Ziggy in your PHP files.

3. Update JavaScript imports

   Replace default imports with named imports:

   # Find and replace in your codebase
   import route from 'ziggy-js' → import { route } from 'ziggy-js'
   
4. Update Vue/React imports

   Move Vue and React imports from subpaths to the root module:

   // Before
   import { ZiggyVue } from 'ziggy-js/vue';
   
   // After
   import { ZiggyVue } from 'ziggy-js';
   
5. Replace check() with has()

   Search for route().check( and replace with route().has(:

   // Before
   if (route().check('home')) { /* ... */ }
   
   // After
   if (route().has('home')) { /* ... */ }
   
6. Test your application

   Thoroughly test all routes and navigation in your application to ensure everything works correctly.

7. Clear all caches

   php artisan config:clear
   php artisan route:clear
   php artisan view:clear
   npm run build # or your build command
   

Summary of Changes

Complete list of breaking changes

• PHP namespace: Tightenco\Ziggy → Tighten\Ziggy (Composer package name unchanged)
• JavaScript exports: Default export removed, use named exports only
• Import paths: Vue/React imports moved from subpaths to root module
• Build formats: Only ES Module builds included (no CommonJS)
• Method removal: check() method removed (use has() instead)
• Internal methods: makeDirectory method of CommandRouteGenerator is now private
• Requirements: Laravel 9+ and PHP 8.1+ required

Getting Help

If you encounter issues during the upgrade process:

• Review the GitHub releases for detailed changelogs
• Check existing issues or open a new one
• Consult the Ziggy documentation for updated usage examples