Migrate Laravel Webpack/Mix to Vite Step by Step Guideline

It has been announced by the Laravel team that Vite now serves as the primary front-end asset bundler. They also launched the official vite-plugin.

To utilize the new Vite integration, it is necessary to upgrade your Laravel to 9.19.0 or upper version. Let's migrate Webpack/Mix to Vite.

Table of Contents

  1. What is Vite
  2. Install Vite and Laravel Plugin
  3. Update NPM Scripts
  4. Configure Vite
  5. Switch to ESM Imports
  6. Update ENV Variables
  7. Replace mix() with @vite
  8. Remove Laravel Mix
  9. Update Test Helpers
  10. Optional: Configure Tailwind
  11. Wrapping Up

What is Vite

Vitejs (pronounced "veet") is a build tool and development server for modern web development. It was created by Evan You, the creator of the popular JavaScript framework Vue.js.

Vitejs aims to provide a faster and more efficient development experience for web developers, by leveraging modern browser features like ES modules and native JavaScript modules.

Install Vite and Laravel Plugin

First, you will need to install Vite and the Laravel Vite Plugin using npm:

npm install --save-dev vite laravel-vite-plugin

Additional Vite plugins, like the Vue or React plugins, might be necessary to be installed for your project.

npm install --save-dev @vitejs/plugin-vue
npm install --save-dev @vitejs/plugin-react

Update NPM Scripts

Update your NPM scripts in package.json:

"scripts": {
-    "dev": "npm run development",
-    "development": "mix",
-    "watch": "mix watch",
-    "watch-poll": "mix watch -- --watch-options-poll=1000",
-    "hot": "mix watch --hot",
-    "prod": "npm run production",
-    "production": "mix --production"
+    "dev": "vite",
+    "build": "vite build"
}

Configure Vite

Create a vite.config.js file in the root of your project:

vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
// import react from '@vitejs/plugin-react';
// import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/css/app.css',
                'resources/js/app.js',
            ],
            refresh: true, // hot refresh
        }),
        // react(),
        // vue({
        //     template: {
        //         transformAssetUrls: {
        //             base: null,
        //             includeAbsolute: false,
        //         },
        //     },
        // }),
    ],
});

Switch to ESM Imports

In order to upgrade an existing application to use Vite, it is necessary to replace any require() statements with import because Vite exclusively supports ES modules.

resources/js/app.js
-require('./bootstrap');
+import './bootstrap';
import Alpine from 'alpinejs';
resources/js/bootstrap.js
-window._ = require('lodash');
+import _ from 'lodash';
+window._ = _;
/**
  * We'll load the axios HTTP library which allows us to easily issue requests
@@ -6,7 +7,8 @@ window._ = require('lodash');
  * CSRF token as a header based on the value of the "XSRF" token cookie.
  */
-window.axios = require('axios');
+import axios from 'axios';
+window.axios = axios;
window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
@@ -18,11 +20,15 @@ window.axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest';
// import Echo from 'laravel-echo';
-// window.Pusher = require('pusher-js');
+// import Pusher from 'pusher-js';
+// window.Pusher = Pusher;

Update ENV Variables

To update your configuration files for hosting environments like Forge, you should modify the prefix in your .env files from MIX_ to VITE_.

- MIX_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
- MIX_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"
+ VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
+ VITE_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"

You also need to set these new variables in bootstrap.js:

-    key: process.env.MIX_PUSHER_APP_KEY,
-    cluster: process.env.MIX_PUSHER_APP_CLUSTER,
+    key: import.meta.env.VITE_PUSHER_APP_KEY,
+    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,

Replace mix() with @vite

You will need to use the @vite Blade directive instead of the mix() helper.

- <link rel="stylesheet" href="{{ mix('css/app.css') }}">
- <script src="{{ mix('js/app.js') }}" defer></script>
+ @vite(['resources/css/app.css', 'resources/js/app.js'])

Your vite.config.js file should have the same entry points as the ones being used.

Remove Laravel Mix

It is now possible to uninstall the Laravel Mix package.

npm remove laravel-mix

You can go ahead and delete your Mix configuration file.

rm webpack.mix.js

Update Test Helpers

If you are using the $this->withoutMix(); helper in your tests, you should replace this with $this->withoutVite():

- $this->withoutMix();
+ $this->withoutVite();

Optional: Configure Tailwind

If you are using Tailwind, perhaps with one of Laravel's starter kits, you will need to create a postcss.config.js file.

Automatically, Tailwind can generate this for you:

npx tailwindcss init -p

Or, you can create it manually:

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Wrapping Up

Now, run the below command:

npm run dev

It'll run Vite server and Vite will watch for file changes.

To build for production, run this command:

npm run build

That's it. To gain a deeper understanding of the migration, kindly peruse this article.

Thanks for reading. ๐Ÿ‘


Software Engineer | Ethical Hacker & Cybersecurity...

Md Obydullah is a software engineer and full stack developer specialist at Laravel, Django, Vue.js, Node.js, Android, Linux Server, and Ethichal Hacking.