Migration Guide

v4.0.0

No API changes, but lots of dependency changes. You'll want to remove all node_modules so Elixir can install the needed dependencies and version.

• Node 16+

• Webpack 5

• Node Sass has been removed in favor of Dart Sass

  • Removes Python dependency

  • Removes usages of node-gyp

• Supports Vue 2 and Vue 3

After the installation, you may notice old Webpack plugins that are no longer needed as of Webpack 5. You may safely remove these.

You will need to tweak your package.json scripts to account for Webpack 5:

{
    "scripts": {
        "dev": "webpack --node-env development",
        "watch": "npm run dev -- --watch",
        "prod": "webpack --node-env production"
    }
}

Lastly, we've introduced a new enableDevtools flag that can be used to force devtools in production environments:

const elixir = require("coldbox-elixir");

elixir.enableDevtools = true;

module.exports = elixir(mix => {
    // ...
});

You do not need to do this for non-production environments. The devtools will be enabled automatically there.

v3.0.0

If you used a previous version of ColdBox Elixir a lot has changed. This guide will step you through the changes.

Dependencies

ColdBox Elixir no longer requires gulp. You can uninstall it.

ColdBox Elixir will install all necessary dependencies when installing or updating it from NPM. There are other dependencies which may be installed on-demand once as you use them.

Running Elixir

Since ColdBox Elixir doesn't use gulp any more, we need to make some changes to our gulpfile.js.

1. Rename gulpfile.js to webpack.config.js.

2. Export the result of elixir()

// webpack.config.js
const elixir = require("coldbox-elixir");

module.exports = elixir(mix => {
    // ....
});

1. (Optional) Create some NPM scripts to make build commands easier to remember. This let's us run npm run dev or npm run watch to build our project.

{
    "scripts": {
        "dev": "webpack",
        "watch": "npm run dev -- --watch",
        "build": "npm run dev -- -p"
    }
}

Asset Names

Due to the way Webpack processes css files, you can no longer have a css file named vendor.

Tasks

The following tasks have been removed from ColdBox Elixir.

• mix.less

• mix.combine

• mix.browserify

• mix.rollup

• mix.exec

If you rely on any of these methods you can either stay with ColdBox Elixir v2 or you can recreate the task yourself.

Method Changes

mix.styles

mix.styles should be replaced with mix.css.

The method signature for mix.css is has changed.

Name	Type	Required	Default	Description
filename	String	true		The filename to bundle.
options	Object	false	(see below)	An object for additional options. Any missing keys will use their default value.
options.name	String	false	The name of the filename without the extension	The name of the outputed bundle
options.outputDirectory	String	false	includes/css	The output directory for the built file.
options.entryDirectory	String	false	resources/assets/css/	The directory where the filename is located.

mix.scripts

mix.scripts should be replaced with mix.js. mix.js will automatically run the code through Babel. Babel is preconfigured with babel-preset-env, but it can be customized by specifying your own .babelrc file in the root of your project. See the Babel docs for more information.

The method signature for mix.scripts has changed.

Name	Type	Required	Default	Description
filename	String	true		The filename to bundle.
options	Object	false	(see below)	An object for additional options. Any missing keys will use their default value.
options.name	String	false	The name of the filename without the extension	The name of the outputed bundle
options.outputDirectory	String	false	includes/js	The output directory for the built file.
options.entryDirectory	String	false	resources/assets/js/	The directory where the filename is located.

mix.webpack

mix.webpack should be replaced with either mix.js or mix.vue depending on your use case. mix.vue includes some extra dependencies and configuration to process .vue files while mix.js will just process your files through Babel.

The method signature for mix.js and mix.vue are the same.

Name	Type	Required	Default	Description
filename	String	true		The filename to bundle.
options	Object	false	(see below)	An object for additional options. Any missing keys will use their default value.
options.name	String	false	The name of the filename without the extension	The name of the outputed bundle
options.outputDirectory	String	false	includes/js	The output directory for the built file.
options.entryDirectory	String	false	resources/assets/js/	The directory where the filename is located.

mix.sass

The method signature for mix.sass has changed.

Name	Type	Required	Default	Description
filename	String	true		The filename to bundle.
options	Object	false	(see below)	An object for additional options. Any missing keys will use their default value.
options.name	String	false	The name of the filename without the extension	The name of the outputed bundle
options.outputDirectory	String	false	includes/css	The output directory for the built file.
options.entryDirectory	String	false	resources/assets/sass/	The directory where the filename is located.

mix.version

Versioning is now the default for a production build (webpack -p). You can also control if the files are versioned by setting the elixir.versioning config property in your webpack.config.js file.

mix.stylesIn and mix.scriptsIn

These methods should be replaced with individual calls to mix.css and mix.js.

Extensions

Extensions that were made for ColdBox Elixir v2 are not compatible with v3. See Writing Elixir Extensions for more information on how to create v3 compatible extensions.

Elixir Config File

The Elixir config file has changed completely. The available configuration options are available in Configuration Options.