Inertia.js v3: What's New and How to Upgrade

Inertia.js v3 has officially launched with significant updates that Laravel developers need to consider. The changes are not just cosmetic; they include the removal of Axios, the exclusive use of ESM, and the dropping of support for React 18 and Svelte 4. In addition, new APIs and a restructured config file promise a more streamlined experience.

Key Updates in v3

The Vite Plugin

One of the most notable changes is the introduction of the Vite plugin. This simplifies the setup process significantly. Previously, configuring an Inertia app required multiple callbacks and entry points. With v3, installing @inertiajs/vite is all you need, and Inertia handles page resolution, code splitting, and SSR configuration automatically.

SSR in Development

Gone are the days of running a separate Node.js server for SSR during development. The Vite plugin now manages this automatically, providing better error messages and fixing flash-of-unstyled-content issues.

New APIs: useHttp Hook and Optimistic Updates

• useHttp Hook: This API provides a cleaner alternative for making HTTP requests without page navigation. It offers reactive processing similar to useForm.
• Optimistic Updates: This feature allows UI changes to be applied immediately before server confirmation, with automatic rollback if the request fails.

Layout Props and Instant Visits

• Layout Props: Pass typed data from page components to persistent layouts without complex workarounds.
• Instant Visits: Improve navigation speed by swapping to the target page component immediately, then merging in page-specific props once the server responds.

Before You Upgrade

Ensure your setup meets the following requirements:

• PHP: Version 8.2 or higher
• Laravel: Version 11 or higher
• React: Version 19
• Svelte: Version 5
• Vite: Version 7+

Upgrade Steps

1. Install the Client Adapter: Choose the appropriate framework:

   npm install @inertiajs/vue3@^3.0
   # or: npm install @inertiajs/react@^3.0
   # or: npm install @inertiajs/svelte@^3.0
   

2. Install the Vite Plugin (recommended):

   npm install @inertiajs/vite@^3.0
   

3. Upgrade the Laravel Adapter:

   composer require inertiajs/inertia-laravel:^3.0
   

4. Republish the Config File:

   php artisan vendor:publish --provider="Inertia\\ServiceProvider" --force
   

5. Clear Cached Views:

   php artisan view:clear
   

Addressing Breaking Changes

• Event Renames: Update global router event names.
• Dependency Removal: Axios, qs, and lodash-es are no longer bundled; install them directly if needed.
• Attribute Changes: Rename inertia attributes to data-inertia.
• Method Changes: Update methods like router.cancel() to router.cancelAll().
• Config File: Review and adjust the new config file structure.

Conclusion

Inertia.js v3 offers a more efficient and streamlined development experience, especially for those using Laravel. While the upgrade may require some initial effort, the benefits of reduced bundle size and improved SSR capabilities make it worthwhile. If your current setup meets the necessary requirements, consider upgrading now to take advantage of these enhancements.