Laravel Asset Bundler

3.1.0 · active · verified Tue Apr 21

Laravel Bundler is a modern and fast asset building tool designed for the Laravel framework, serving as a direct alternative to Laravel Mix. It leverages Webpack 5 for bundling, Babel 7 for JavaScript transpilation, and esbuild for high-performance CSS and JavaScript minification. The current stable version is 3.1.0, with an active development cadence indicated by recent releases and continuous integration. Key differentiators include its focus on better defaults, explicit support for ESM via `.mjs` configuration files, and dedicated 'recipes' for integrating popular frontend frameworks like Vue.js (v2 and v3) with pre-configured loaders and plugins, including full HMR support. It generates a `mix-manifest.json` compatible with Laravel's `mix()` helper, ensuring a smooth transition for existing Laravel projects.

Common errors

```
Error: Cannot find module 'webpack/lib/node/NodeTemplatePlugin'
```
cause Webpack is not installed or the installed version is incompatible with laravel-bundler.

fix Ensure `webpack` is installed as a dev dependency: `npm install --save-dev webpack@^5`.
```
SyntaxError: Cannot use import statement outside a module
```
cause The Webpack configuration file (e.g., `webpack.config.js`) is attempting to use ESM `import` statements without being treated as an ES module.

fix Rename your `webpack.config.js` to `webpack.config.mjs` and ensure `"type": "module"` is present in your `package.json`.
```
Module not found: Error: Can't resolve 'vue'
```
cause A Vue recipe is being used, but the `vue` package (and potentially `vue-template-compiler`) has not been installed.

fix Install the required Vue version and its associated compiler: `npm install --save-dev vue@^2 vue-template-compiler@^2` (for Vue 2) or `npm install --save-dev vue@^3` (for Vue 3).

Warnings

breaking This package is not compatible with `laravel-mix`. Users must remove `laravel-mix` and its associated `webpack.mix.js` configuration before installing and using `laravel-bundler`.
Fix: Uninstall `laravel-mix` (`npm uninstall laravel-mix`) and delete `webpack.mix.js`. Then, install `laravel-bundler` and create a `webpack.config.mjs`.
gotcha The project requires Node.js version 20.14.0 or higher. Older Node.js versions may lead to build failures or unexpected behavior.
Fix: Upgrade your Node.js installation to version 20.14.0 or newer using a version manager like nvm or fnm.
gotcha This package is designed for an ESM-first workflow. Your `package.json` should include `"type": "module"`, and your Webpack configuration file should be named `webpack.config.mjs` to ensure proper `import`/`export` syntax is used.
Fix: Add `"type": "module"` to your `package.json` and rename your Webpack config file to `webpack.config.mjs`.
gotcha When using specific recipes (e.g., `vue2Recipe`, `vue3Recipe`), you must manually install the required framework and its associated loader/compiler dependencies (e.g., `vue`, `vue-template-compiler` for Vue 2) as `laravel-bundler` does not install them automatically.
Fix: Consult the relevant recipe documentation and install all listed peer dependencies using `npm install --save-dev [package-name]`.

Install

npm install laravel-bundler npm
yarn add laravel-bundler yarn
pnpm add laravel-bundler pnpm

Imports

createConfig
wrong:
```
const { createConfig } = require('laravel-bundler');
```
correct:
```
import { createConfig } from 'laravel-bundler';
```
This package is ESM-first; configuration files typically use `import` syntax and `.mjs` extension.
vue2Recipe
wrong:
```
import { vue2Recipe } from 'laravel-bundler';
```
correct:
```
import vue2Recipe from 'laravel-bundler/src/recipes/vue-2.js';
```
Recipes are imported from specific paths within the package. Ensure 'vue' and related dependencies are installed for the recipe.
vue3Recipe
```
import vue3Recipe from 'laravel-bundler/src/recipes/vue-3.js';
```
Similar to vue2Recipe, imported from a specific path. Requires 'vue' v3 and related dependencies to be installed separately.

Quickstart

This quickstart demonstrates how to set up `laravel-bundler` for a Laravel project with Vue.js v2, including the necessary `webpack.config.mjs`, a basic `app.js` entry point, and essential `package.json` scripts and dev dependencies for a functional build process.

import webpack from 'webpack';
import { createConfig } from 'laravel-bundler';
import vue2Recipe from 'laravel-bundler/src/recipes/vue-2.js';

// webpack.config.mjs
export default createConfig({
    entry: {
        app: './resources/js/app.js'
    },
    plugins: [],
    // Other webpack configurations
},
vue2Recipe);

// resources/js/app.js
import Vue from 'vue';
import 'bootstrap/dist/css/bootstrap.css';
import RegularComponent from './components/Regular.vue';

new Vue({
    el: "#app",
    components: {
        RegularComponent
    }
});

// package.json (excerpt)
/*
{
    "type": "module",
    "scripts": {
        "dev": "webpack --config-node-env=development --progress",
        "prod": "webpack --config-node-env=production --progress"
    },
    "devDependencies": {
        "laravel-bundler": "^3",
        "webpack": "^5",
        "vue": "^2",
        "bootstrap": "^4",
        "@babel/preset-env": "^7",
        "vue-template-compiler": "^2"
    }
}
*/

view raw JSON →