Migrating Traditional Laravel Mix to Vite

On June 2022, Laravel has announced a huge accomplishment by Laravel Team that Vite is now the default frontend asset bundler for new laravel apps well as with updates of Breeze and Jetstream packages replacing Laravel mix.

As we know, Laravel comes with Laravel Mix, an abstraction of Webpack. Vite takes a new level approach to improve the experience of front-end development. They also update the Laravel documentation page giving you a complete overview of all your frontend options with Laravel applications.

Why Vite?

Vite is a new breed of frontend build tool that provides an extremely fast development environment and bundles your code for production. Based on comparison i made, Vite perform 4–5x faster than Laravel mix.

Vite serves native ES modules transpiled with esbuild from the dev server. This means there’s a lot less bundling to do and results in a very fast developer experience. For production builds, Vite uses Rollup to bundle the assets.

Migrating from Laravel Mix to Vite

Laravel already includes migration guide in their official documentation pages and also in Github. In this article, here where we show how easily we can migrate from Laravel Mix to Vite.

1. Install Vite and the Laravel Plugin
2. Configure Vite
3. Update NPM Script
4. Update environment variables
5. Replace mix() with @vite()
6. Replace require to import
7. Configure Tailwind
8. Configure Git ignore
9. Remove Laravel Mix
10. Testing
11. Rollback

Before we start migrating, it is recommended to create new GIT branches just for this changes. Incase of errors, we can rollback to the original state.

Note that, to make use of the new Vite integration, you will need to update to your laravel framework at least version 9.19.0

Install Vite and the Laravel Plugin

First, you will need to install Vite and the Laravel Vite Plugin using your npm package manager of choice:

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

Configure Vite

Create a vite.config.js file in the root of your project and paste below configuration

import { defineConfig} from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

If you are migrating aliases from your webpack.mix.js file to your vite.config.js file, you should ensure that the paths start with /. For example, resources/js would become /resources/js:

import { defineConfig} from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
    resolve: {
        alias: {
            '@': '/resources/js'
        }
    }
});

For the convenience, the Laravel Vite plugin automatically adds an @ alias for your /resources/js directory unless you want to make customization.

Update NPM Script

Update your NPM scripts in package.json. Replace the scripts with below

"scripts": {
      "dev": "vite",
      "build": "vite build"
}

Sometime you want to build while you make a changes. You can add build watch in the scripts

"scripts": {
    "dev": "vite",
    "build": "vite build",
    "watch" : "vite build --watch"
},

It’s useful when you want to automate your build in server when there is any change

Update environment variables

You need to update the environment variables in your .env files to use the VITE_ prefix instead of MIX_:

- 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 will also need to update these references in your JavaScript code to use the new variable name and Vite syntax:

window.Echo = new Echo({
    broadcaster: 'pusher',
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    wsHost: import.meta.env.VITE_PUSHER_HOST ?? `ws-${import.meta.env.VITE_PUSHER_APP_CLUSTER}.pusher.com`,
    wsPort: import.meta.env.VITE_PUSHER_PORT ?? 80,
    wssPort: import.meta.env.VITE_PUSHER_PORT ?? 443,
    forceTLS: (import.meta.env.VITE_PUSHER_SCHEME ?? 'https') === 'https',
    enabledTransports: ['ws', 'wss'],
});

But if you wish to maintain the MIX_ prefix, you can configure in vite config

export default defineConfig({
    ...
    envPrefix: 'MIX_'
});

Replace mix() with @vite()

Now, we need to replace mix() helper with @vite() blade directive.

<link rel="stylesheet" href="{{ mix('css/app.css') }}">
<script src="{{ mix('js/app.js') }}" defer></script>

replace with this

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

The entry points should match those used in your vite.config.js.

Replace require to import

Since Vite only supports ES modules, if you are upgrading an existing application you will need to replace any require() statements with import. You may refer to this pull request for an example.

For example

inside resources/js/app.js

-require('./bootstrap');
+import './bootstrap';

for resources/js/bootstrap.js, if you not yet touch this file, simple copy the file from the latest branch Laravel in github. Else, you need to change like sample above.

Configure Tailwind

For those who are using TailwindCSS, you will need to create a postcss.config.js file. Run command below and Tailwind will generate this for you automatically.

npx tailwindcss init -p

Or, you can create it manually:

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

If you are using other PostCSS plugins, such as postcss-import, you will need to include them in your configuration.

Configure Git ignore

Vite will place all of your build assets into a build subdirectory inside public directory. You may wish to add this directory to your .gitignore file if you prefer to build your assets on deploy instead of committing them to your repository.

public/build

Remove Laravel Mix

Now, we now can safely remove Laravel Mix package.

npm remove laravel-mix

And you may remove your Mix configuration file:

rm webpack.mix.js

If you are using StyleCI and have ignored the webpack.mix.js file in your configuration, you may also wish to remove the ignore rule.

Testing

You should now be able to build your assets using dev command. This will also invoke the Vite server and Vite will watch for file changes:

npm run dev

Alternatively, if you need to build files without watching or if you need to build them for production, you may use the build command:

npm run build
npm run watch

For further information on how to use Vite, please check out the Laravel Vite documentation.

Rollback

In case you have problem on migrating to Vite and you want to rollback, you can easily stash everything since you have Git version control. Else, you need to manually revert all the changes you have made. You may follow this guideline to rollback

Troubleshooting

If you have followed the upgrade guide, but are still having issues you should try to run php artisan optimize:clear to clear any compiled view assets or caches.

References