Introduction

Laravel is a modern open-source PHP framework for web applications, created by Tailor Otwell. It has been designed to produce elegant code, run fast and simplify web development. It comes with a lot of tools such as a router, a queue manager (Horizon), a CLI (Artisan), and a front builder (Mix).

Laravel Mix is a tool providing front assets compilation with various preprocessor for JS and CSS. Mix is based on the great Webpack builder and provides a higher level API to simplify pre-processing configuration.

Unfortunately, Laravel Mix has its own limits: it doesn’t provide a great flexibility when dealing with multiple frontend application hosted in the same projet; mix cannot generate multiple vendors, split assets easily to different folders. Hopefully, I have found an elegant solution to fix this issue and I hope it will help you!

Follow the guide!

Trying to split dependencies into different vendors using Laravel Mix

Let’s say you have a Laravel project with two frontend applications:

  • A back-office application using bootstrap and jQuery and to perform AJAX request on API endpoints ;
  • A customer-facing application powered by VueJS to provide a more advanced UX.

Why would I want to split vendors?

These two front applications require totally different Javascript packages. Additionally, they may share some dependencies. For performances reasons, we want to separate these package into two different vendors that will be loaded separately by each application; you don’t want your VueJS application to load bootstrap and jQuery for nothing.

Unfortunately, if you are using Laravel Mix (and you should as it simplify building process!), you won’t be able to build two separate vendors for your two front applications out of the box.

[Optional] Instantiate a Laravel project with two front applications

This whole section is optional. I want to provide a specific and real context before describing the solution and discussing performances improvements. Plus, all sources described here are available on Luckey Homes GitHub public repository. Hope it will give you a better understanding of our problem!

Project setup

First step, install Laravel installer globally on your computer:

composer global require laravel/installer

You may need to add ext-zip PHP extension to successfully install latest version.

Once done, run Laravel CLI:

laravel new laravel-mix-multiple-vendors
cp .env.example .env
php artisan key:generate

Create a .env file to store environment variable and generate application key:

Finally, start your server by typing:

php -S localhost:8080 -t ./public

Two front applications: backoffice and customers

We are going to modify this basic Laravel setup to create two different front applications. I won’t focus on CSS in this guide. First, create two directory in ressources/js folder:

mkdir ressources/js/backoffice && mkdir ressources/js/customers

Then:

mv ressources/js/bootstrap.js ressources/js/backoffice/bootstrap.js
rm ressources/js/app.js
rm ressources/js/components/ExampleComponent.vue
rm ressources/views/welcome.blade.php

In backoffice folder, create a backoffice.js file. This file is our back-office JS entry point. Let’s use it to make sure jQuery is running: 

ressources/js/backoffice/backoffice.js

In customers folder, create a customers.js (our customer application entry point) file and a HelloWorld.vue component:

ressources/js/customers/customers.js
ressources/js/customers/HelloWorld.vue

Laravel project created through Laravel CLI already comes with jquery, bootstrap, and VueJS. In order to install JS dependencies, run:

yarn install

Create two routes in your Laravel routes/web.php: (and you can delete default welcome route by the way)

routes/web.php

Create corresponding views in ressources/views folder and make sure these views are loading corresponding JS entry points. These JS entry points are loaded through mix() helper that looks into your public/mix-manifest.json folder and generate link to public/js folder once built by Laravel Mix.

ressources/views/backoffice.blade.php
ressources/views/customers.blade.php

At this point, your ressources folder should look like this:

ressources folder with two separate front applications

Basic build configuration

Update laravel mix config (webpack.mix.js):

webpack.mix.js

And then build your assets using:

npm run dev

Here is what your public folder should look like:

Browsing our applications

Open a browser and go to http://localhost:8080/customers to view Customers application. (I agree it’s ugly!). If you can see ‘Hello World’, that means that jQuery is loaded. In your Network tab (developer tools), you will see that customer.js is loaded ~300KB.

First glance at our beautiful customers application

Having a look to Back-Office application: Vue seems to be loaded and backoffice.js weights ~1.0MB:

Backoffice application

That’s it! At this step, we are not using vendors at all. customer.js and backoffice.js have been built by Laravel Mix (and Webpack) and contains exactly what they need. But that’s not perfect for many reasons:

  • as applications get more complex, we want to separate pages script from packages dependencies in order to optimize performances: a heavy vendor containing dependencies is loaded once and then cached by the browser while pages scripts are loaded depending on the page user is on ; Using Webpack, you can dynamically load your assets from your vendor, only when they are needed. This method significantly improve performances ;
  • to improve User Experience, developers try to provide a first print of the page as soon as possible. That’s why it’s good to separate must-have JS scripts from secondary/heavy scripts that can be loaded later into different files.

Trying to build multiple vendors

Let’s try to go one step further and set up vendors. Based on this official documentation, we can update our webpack.mix.js script in the following way:

webpack.mix.js

Run npm run dev again. You should get the following output:

We note that even if we add .extract() instruction on backoffice.js, backoffice vendor.js file is attached to customers folder. And if you try to split your dependencies into many vendors using multiple extract() instruction, you won’t be able to build your assets in multiple vendors:

Nice try!

At this point, you might be tempted to use this vendor.js in your two applications by adding the following lines to your two views template:

<script src="{{ mix('js/customers/manifest.js') }}"></script>
<script src="{{ mix('js/customers/vendor.js') }}"></script>

If you refresh your applications, you will get:

Vendor.js size is 1.3MB (makes sense!). It’s very heavy compared to 300KB we had before!

Vendors.js is loaded here too. At least, it will be cached by user’s browser!

How can we build multiple vendors using Laravel Mix?

One solution: add option to your npm scripts

It may not be the only solution, but this is the only one I could get working! Here is our plan:

  • Write different Laravel Mix configuration file for each front application we have ;
  • During building process, build all different Laravel mix configurations separately ;
  • Make sure Laravel is able to mix between built folders!

Split your build into multiple mix files

Start by creating two different mix files: webpack.backoffice.mix.js and webpack.customers.mix.js. These two files are using their own entry point and are defining their own vendor:

Backoffice application webpack config
Customers application webpack config

Do not take care of .mergeManifest() for now! It’s explained below.

Instead of running npm run dev, let’s specify to our npm script what application should be built. This can be achieved by using  npm scripts options (npm –section=backoffice run dev or npm –section=customers run dev) and updating the following main webpack.mix.js script, so it redirects to our specific webpack.{app.mix.js:

Our new webpack.mix.js

Options passed to npm are available in scripts using process.env.npm_config_{option}. 

If you try to build your assets now, you will face one last problem. When writing links to your assets from laravel templates, you usually want to use {{ mix() }} helper. To resolve dependencies, mix() helper takes a look at public/mix-manifest.json file. Unfortunately, while building your application in multiple steps (first backoffice, then customers.js), this mix-manifest.json will be overwritten.

To fix it, you can use laravel-mix-merge-manifest package:

yarn add laravel-mix-merge-manifest

And add .mergeManifest() instruction to your webpack.{app}.mix.js files (see above).

Finally, run:

npm --section=backoffice run dev && npm --section=customers run dev

Successful output:

Have a look to your mix-manifest.json and update mix path in your blade templates to use dedicated vendors:

public/mix-manifest.json
<script src="{{ mix('js/customers/manifest.js') }}"></script>
<script src="{{ mix('js/customers/vendor.js') }}"></script>
<script src="{{ mix('js/customers/customers.js') }}"></script>

// and

<script src="{{ mix('js/backoffice/manifest.js') }}"></script>
<script src="{{ mix('js/backoffice/vendor.js') }}"></script>
<script src="{{ mix('js/backoffice/backoffice.js') }}"></script>

Browse your two applications again and… TADAA!

Backoffice application
Customers application

We now have very light customers.js and backoffice.js file and dedicated vendors (300KB + 999KB). Perfect!

Additional tips

Here is one protip! In order to run both build in one command concurrently:

yarn add concurrently

And update your package.json script section:

And then:

npm run dev-all

Conclusion

Laravel mix is powerful but has its own limit. Understanding built process from npm scripts to mix() helper helped me a lot while designing this workaround.

I’ve been struggling a few hours with this problem, without finding any proper solution on the Internet. I want to share my own solution with you and I hope this will help some of you building robust Laravel applications!

All sources described here are available on a GitHub public repository.


Leave a Reply

Your email address will not be published. Required fields are marked *