# 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: ```json { "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: ```javascript 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()` ```javascript // 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. ```javascript { "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.](https://coldbox-elixir.ortusbooks.com/writing_elixir_extensions) ## 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`](https://coldbox-elixir.ortusbooks.com/working_with_scripts). `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](https://babeljs.io/docs/en/babelrc) 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`](https://coldbox-elixir.ortusbooks.com/working_with_scripts) or [`mix.vue`](https://coldbox-elixir.ortusbooks.com/vuejs_integration) 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*](https://coldbox-elixir.ortusbooks.com/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.*](https://coldbox-elixir.ortusbooks.com/configuration_options) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://coldbox-elixir.ortusbooks.com/migration_guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.