Replacing Laravel Mix with Vite

Published under Laravel.

In this guide, we'll replace Laravel Mix with Vite in a Laravel Jetstream (Inertia/Vue) application.

Vite is a build tool created by Evan You (creator of Vue) which utilizes the availability of native ES modules in the browser. Read more about Vite on the Why Vite page.

NOTE: This is my first time using Vite. I do not have a full understanding of Vite at the time of writing this post. If you see anything incorrect with this setup, please let me know on Twitter, @owenconti.

TLDR;

If you want to get up and running right away, consider using the Laravel Vite package created by Enzo Innocenzi which is an opinionated setup that handles everything for you.

TLDR; extended (Vue 3)

Note: Vite recommends not omitting file extensions for custom import types, ie: .vue files.

https://vitejs.dev/config/#resolve-extensions

This means you should ensure all of your imports use the .vue extension throughout your codebase.

Install npm dependencies:

Uninstall Laravel Mix dependency and remove the config file:

Setup PostCSS:

Create vite.config.js file:

Ensure environment variables are set:

Install Laravel Vite Manifest PHP package to include Vite's output files from the generated manifest:

Add the Blade directive from the package which includes the generated assets:

Add npm scripts to run Vite:

Import your .css file inside your entry .js file:

Make a few minor changes for Inertia:

That's the quick version. If you want to understand more about each step, keep reading.

Walkthrough

Here's what we're going to setup:

- Replace a default Laravel Mix setup

- Compile JS (Vue)

- Compile CSS (Tailwind)

If your existing Laravel Mix is more complicated than that, your mileage may vary with this guide.

We'll setup both a Vue 2 version and a Vue 3 version.

Setting up the vite.config.js file

To start off, we need to create a vite.config.js file in the root of the repo.

Vue 2:

Vue 3:

Let's run through each section.

Plugins

The plugins section tells Vite how to handle .vue files.

Root

The root option tells Vite what directory is the root directory of our application. Assets will be output relative from this directory. For example, resources/js/app.js will be output as js/app.js.

Base

The base option tells Vite where the assets will be served from once deployed. This is equivalent to the publicPath option in Webpack. We pull the ASSET_URL from the environment file so that our build uses the correct path when deployed to a CDN.

Note: Make sure the ASSET_URL is set correctly in your .env file when building. If you're deploying with Vapor, Vapor will set the ASSET_URL for you.

Build

The build section tells Vite how the application should be built.

- outDir - The output directory that the application should be built to.

- emptyOutDir - We set this to true to suppress a warning from Vite that says we are emptying the outDir when it exists outside project root (resources).

- manifest - Tells Vite to publish a manifest file, which we'll use in production builds to find the correct file hash names.

- target - Tells Vite which browsers should be supported, you can read more on Vite's website.

- rollupOptions - These are specific options you can provide to Rollup (which Vite uses to bundle the application). In our case, we need to provide Rollup with our main entry file.

Server

The server section instructs Vite on how to start the development server.

- strictPort - Forces Vite to start on the port we specified. Vite will exit if the port is in use as opposed to incrementing the port number which is default behaviour.

- port - Which port the Vite development server should run on.

Resolve

The resolve section is optional. In my case, I am using it to alias @ to /js.

Optimize Dependencies

We need to tell Vite to pre-bundle the dependencies that do not ship a ESM version. The array you pass here will vary based on the dependencies in your project.

Note: portal-vue is not necessary in Vue 3 projects.

Dependencies to install

You'll need to make sure you install the following JS dependencies:

Setup PostCSS

In order to compile Tailwind, we need to move our PostCSS configuration from webpack.mix.js into a dedicated postcss.config.js file, which resides at the root of your repo:

Update your Inertia JS setup

Here's my full app.js that configures Inertia:

Environment variables

The asset path is controlled via the standard Laravel ASSET_URL environment variable. However, we don't provide a default, so it must be set in order for everything to work.

We need to change a couple of environment variables based on if we're running the local development server vs if we're running a production build:

Install the Laravel Vite Manifest package

I wrote a very simple Laravel package to pull the contents of the Vite manifest and include them in your Blade view. The main logic for the package is sourced from https://github.com/andrefelipe/vite-php-setup.

The package uses the APP_ENV and ASSET_URL environment variables to decide how to load the assets.

Add the Blade directive to include Vite's compiled assets:

Remove Laravel Mix

Don't forget to remove Laravel Mix and its configuration file:


Thanks for reading!

Did you find this post useful? Let me know on Twitter! If you found an issue with the content, submit a pull request!

Subscribe to my newsletter to know when I publish more content in the future.

❤️ Likes: 4
📣 Retweets: 0
💬 Replies: 0
🙊 Mentions: 0