On Tuesday, the 27th of June 2022, Laravel 9.19.0 with Vite support was released. Learn how to migrate a Laravel Inertia Vue app to Laravel Vite.

How to migrate a Laravel Inertia Vue App to Vite

On Tuesday, the 27th of June 2022, Laravel 9.19.0 was released. It introduced significant changes regarding frontend asset building. Laravel is moving from Laravel Mix, a wrapper around Webpack created by Jeffrey Way, to Vite. This is no breaking change for existing applications, but all newly created Laravel Installations come with Vite instead of Mix by default.

Vite has some amazing benefits when using it. The main advantage is; It makes your development workflow pretty fast.

The migration on the Laravel Site is explained pretty well in the Migration Guide, so I'm not going to dig deeper into this.

This process can also run automatically by a beautiful service named Laravel Shift. They have done an excellent Laravel mix to Vite converter, and the best of all - it's free. Laravel Shift Mix to Vite Converter

We will focus on the points that must be done on top of that, especially when migrating a SPA with Inertia & VueJS 3.0. Some of these points can also be adapted to React or Svelte apps.

How to start

Considering you have followed the migration guide, the next step is to check if your application still works. Usually, you will run into problems, especially in bigger, more complex applications. If not, you are finished here. Congratulations! First, you must start your development server with npm run dev, and there should be no issues. Next, open your Browser's javascript console on your local dev environment.

In my case, whenever there were some issues, I received a blank page or some basic features like navigating wasn't not working. In the Javascript console should be some errors at this point. The job is now to fix those errors one after the other; if there are no errors, the migration process is finished. If you are running integration tests with Cypress or Laravel Dusk, you can rely on your test results instead of doing it manually in the Browser.

I'm going to list some common errors and how to fix them:

Uncaught (in promise) TypeError: Failed to fetch dynamically imported module

When this error appears. Vite has difficulties loading some modules. In most cases this is a problem with the component imports. With Vite, your component imports must be referenced by their full name.

import JetButton from '@/Jetstream/Button';

has to be changed to

import JetButton from '@/Jetstream/Button.vue';

Take care. This error even happens when a child component loads other nested components. So your whole Component tree has to be safe at this point.

Uncaught ReferenceError: require is not defined

This error happens when you use require instead of ESM module imports. Vite, by its architecture, only works with module imports. So your require calls have to be replaced with import. Swítching to module imports can sometimes be tricky and can require refactoring.

Bootstrap.js with requires

window._ = require('lodash');
window.axios = require('axios');

window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';

import Echo from 'laravel-echo';

window.Pusher = require('pusher-js');

window.Echo = new Echo({
    ...
});

Bootstrap.js with imports

import _ from 'lodash';
import axios from 'axios';
import Echo from 'laravel-echo';
import Pusher from 'pusher-js';

window._ = _;

window.axios = axios;

window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';

window.Pusher = Pusher;

window.Echo = new Echo({
    ...
});

WebSocket connection to 'wss://your-app.test:3000/' failed

This error can happen if you are serving your dev environment per HTTPS; there can be certificate issues. You find a solution for this for Laravel Valet here https://twitter.com/freekmurze/status/1541837713367777280

If you are confident your application works in your development environment, you can bundle all your assets with npm run build. And check if everything works. If not, repeat fixing problems.

Final Words

In my opinion, the Vite integration in the Laravel ecosystem is a big step to sustaining a modern fast development experience. But I won't recommend migrating all of your applications to Vite now - but you should do it in the middle term. It's a pretty new integration, and there will be some errors in the early days.

I always love to have some feedback you can contact me on Twitter or per mail if you want! Have a nice week!