From bf17409149057782a0d48afc8e1642d5d9a86763 Mon Sep 17 00:00:00 2001 From: Jack Wilkinson <31214002+jaxwilko@users.noreply.github.com> Date: Tue, 16 Jul 2024 06:44:58 +0100 Subject: [PATCH] Added vite documentation and split out mix from asset compilation (#200) Documents https://github.com/wintercms/winter/pull/1141 --- console/asset-compilation-mix.md | 170 ++++++++++++++++ console/asset-compilation-vite.md | 216 +++++++++++++++++++++ console/asset-compilation.md | 309 +++--------------------------- 3 files changed, 410 insertions(+), 285 deletions(-) create mode 100644 console/asset-compilation-mix.md create mode 100644 console/asset-compilation-vite.md diff --git a/console/asset-compilation-mix.md b/console/asset-compilation-mix.md new file mode 100644 index 00000000..f216f8c5 --- /dev/null +++ b/console/asset-compilation-mix.md @@ -0,0 +1,170 @@ +# Asset Compilation - Mix + +## Registration + +By default, any plugin or theme containing a `winter.mix.js` file at its root will be automatically registered. Registered items can be viewed with the `mix:list` command. + +The following sections document additional ways to configure a Mix package, these are only required if you need additional customization. + +### Registering plugins + +To register frontend assets to be compiled through Mix in your plugin, simply return an array with the package names as the keys and the package paths relative to the plugin's directory as the values to register from your [`Plugin.php`](../plugin/registration) registration file's `registerMixPackages()` method. See below example. + +```php +public function registerMixPackages(): array +{ + return [ + 'custom-package-name' => 'assets/js/build.mix.js', + ]; +} +``` + +### Registering themes + +Registration of asset compilation of themes is even easier, and can be done by adding a `mix` definition to your [theme information file](../themes/development#theme-information-file) (`theme.yaml`). + +```yaml +name: "Winter CMS Demo" +description: "Demonstrates the basic concepts of the frontend theming." +author: "Winter CMS" +homepage: "https://wintercms.com" +code: "demo" + +mix: + : winter.mix.js +``` + +The `mix` definition takes any number of registered packages as a YAML object, with the key being the name of the package as a kebab-case string and the location of your `winter.mix.js` file relative to the theme's root directory. + +For example, if you want to register two packages called `demo-theme-style` and `demo-theme-shop` located in the assets folder, you would use the following definition: + +```yaml +name: "Winter CMS Demo" +description: "Demonstrates the basic concepts of the frontend theming." +author: "Winter CMS" +homepage: "https://wintercms.com" +code: "demo" + +mix: + demo-theme-style: assets/style/winter.mix.js + demo-theme-shop: assets/shop/winter.mix.js +``` + +### Registering custom + +You can configure a custom mix package that sits outside of plugins and themes. + +```php +use System\Classes\CompilableAssets; + +CompilableAssets::instance()->registerPackage( + name: 'my-custom-package', + path: '/path/to/winter.mix.js', + type: 'mix' +); +``` + +## Automatic Mix configuration + +The command `mix:config` will allow you to automatically generate a basic Mix config which you can then build on top of. + +```bash +php artisan mix:config [--tailwind] [--vue] [--stubs] +``` + +By default, the `mix:config` command will only generate the basic `winter.mix.js` config file. If you would like Winter to pre-configure your package for a certain library, you can provide any of the following flags. + +- `--tailwind` will configure your package for [tailwindcss](https://tailwindcss.com/) +- `--vue` will configure your package for [vue.js](https://vuejs.org/) + +The `--stubs` flag will tell Winter to automatically pre-populate css/js files with a basic setup of your chosen libraries. + +For example, the following with configure the plugin `Acme.Example` with tailwind and create `plugins/acme/example/assets/src/acme-example.css` with a tailwind setup. + +```bash +php artisan mix:config acme.example --tailwind --stubs +``` + +## Manual Mix configuration + +The Mix configuration file (`winter.mix.js`) is a configuration file that manages the configuration of Laravel Mix itself. In conjunction with the `package.json` file that defines your dependencies, this file defines how Laravel Mix will compile your assets. + +You can [review examples](https://laravel-mix.com/docs/6.0/examples) or the [full Mix API](https://laravel-mix.com/docs/6.0/api) at the [Laravel Mix website](https://laravel-mix.com). + +Your `winter.mix.js` file must include Mix as a requirement, and must also define the public path to the current directory, as follows: + +```js +const mix = require('laravel-mix'); + +// For assets in the current directory +// mix.setPublicPath(__dirname); + +// For assets in a /assets subdirectory +mix.setPublicPath(__dirname + '/assets'); + +// Your mix configuration below +``` + +### Paths + +When the `winter.mix.js` file is evaluated, regardless of where you ran `mix:compile` from, the working directory is set to the parent directory of the `winter.mix.js` file. That means that any relative paths used in the configuration will be relative to the current directory of the `winter.mix.js` file. + +>**NOTE:** Winter's [path symbols](../services/helpers#path-symbols) are also supported in the `winter.mix.js` file. + +## Commands + +### Install Node dependencies + +```bash +php artisan mix:install [-p ] [--npm ] +``` + +The `mix:install` command will install Node dependencies for all registered Mix packages. + +This command will add each registered package to the `workspaces.packages` property of your root `package.json` file and then run and display the results of `npm install` from your project root to install all of the dependencies for all of the registered packages at once. + +You can optionally provide a `-p` or `--package` flag to install dependencies for one or more packages. To define multiple packages, simply add more `-p` flags to the end of the command. + +If the command is run with a `-p` or `--package` flag and the provided package name is not already registered and the name matches a valid module, plugin, or theme package name (modules are prefixed with `module-$moduleDirectory`, themes are prefixed with `theme-$themeDirectory`, and plugins are simply `Author.Plugin`) then a `winter.mix.js` file will be automatically generated for that package and will be included in future runs of any mix commands through the [automatic registration](#automatic-registration) feature. + +The `--npm` flag can also be provided if you have a custom path to the `npm` program. If this is not provided, the system will try to guess where `npm` is located. + +### List registered Mix packages + +```bash +php artisan mix:list [--json] +``` + +The `mix:list` command will list all registered Mix packages found in the Winter installation. This is useful for determining if your plugin or theme is correctly registered. + +The command will list all packages, as well as the directory for the asset and the configuration file that has been defined during registration. + +A json formatted list of packages can be printed by specifying the `--json` flag. + +### Compile a Mix packages + +```bash +php artisan mix:compile [-p ] [-f|--production] [-- ] +``` + +The `mix:compile` command compiles all registered Mix packages, running each package through Laravel Mix for compilation. + +By specifying the `-p` flag, you can compile one or more selected packages. To define multiple packages, simply add more `-p` flags to the end of the command. + +The `--no-progress` flag can be added in order to suppress the mix progress output. Useful if you want to only view the webpack output. + +By default, all packages are built in "development" mode. If you wish to compile in "production" mode, which may include more optimisations for production sites, add the `-f` or `--production` flag to the command. + +The command will generate a report of all compiled files and their final size once complete. + +If you wish to pass extra options to the Webpack CLI, for special cases of compilation, you can add `--` to the end of the command, followed by [any parameters](https://webpack.js.org/api/cli/) as per the Webpack CLI options. + +### Watch a Mix package + +```bash +php artisan mix:watch [-f|--production] [-- ] +``` + +The `mix:watch` command is similar to the `mix:compile` command, except that it remains active and watches for any changes made to files that would be affected by your compilation. When any changes are made, a compile is automatically executed. This is useful for development in allowing you to quickly make changes and review them in your browser. + +With this command, only one package can be provided and watched at any one time. diff --git a/console/asset-compilation-vite.md b/console/asset-compilation-vite.md new file mode 100644 index 00000000..523f064d --- /dev/null +++ b/console/asset-compilation-vite.md @@ -0,0 +1,216 @@ +# Asset Compilation - Vite + +## Registration + +By default, any plugin or theme containing a `vite.config.mjs` file at it's root will be automatically registered. Registered items can be viewed with the `vite:list` command. + +The following sections document additional ways to configure a Vite package, these are only required if you need additional customization. + +### Registering plugins + +To register frontend assets to be compiled through Vite in your plugin, simply return an array with the package names as the keys and the package paths relative to the plugin's directory as the values to register from your [`Plugin.php`](../plugin/registration) registration file's `registerVitePackages()` method. See below example. + +```php +public function registerVitePackages() +{ + return [ + 'custom-package-name' => 'assets/js/build.vite.js', + ]; +} +``` + +### Registering themes + +Registration of asset compilation of themes is even easier, and can be done by adding a `vite` definition to your [theme information file](../themes/development#theme-information-file) (`theme.yaml`). + +```yaml +name: "Winter CMS Demo" +description: "Demonstrates the basic concepts of the frontend theming." +author: "Winter CMS" +homepage: "https://wintercms.com" +code: "demo" + +vite: + : vite.config.mjs +``` + +The `vite` definition takes any number of registered packages as a YAML object, with the key being the name of the package as a kebab-case string and the location of your `vite.config.mjs` file relative to the theme's root directory. + +For example, if you want to register two packages called `demo-theme-style` and `demo-theme-shop` located in the assets folder, you would use the following definition: + +```yaml +name: "Winter CMS Demo" +description: "Demonstrates the basic concepts of the frontend theming." +author: "Winter CMS" +homepage: "https://wintercms.com" +code: "demo" + +vite: + demo-theme-style: assets/style/vite.config.mjs + demo-theme-shop: assets/shop/vite.config.mjs +``` + +### Registering custom + +You can configure a custom vite package that sits outside of plugins and themes. + +```php +use System\Classes\CompilableAssets; + +CompilableAssets::instance()->registerPackage( + name: 'my-custom-package', + path: '/path/to/vite.config.mjs', + type: 'vite' +); +``` + +## Automatic Vite configuration + +The command `vite:config` will allow you to automatically generate a basic Vite config which you can then build on top of. + +```bash +php artisan vite:config [--tailwind] [--vue] [--stubs] +``` + +By default, the `vite:config` command will only generate the basic `vite.config.mjs` config file. If you would like Winter to pre-configure your package for a certain library, you can provide any of the following flags. + +- `--tailwind` will configure your package for [tailwindcss](https://tailwindcss.com/) +- `--vue` will configure your package for [vue.js](https://vuejs.org/) + +The `--stubs` flag will tell Winter to automatically pre-populate css/js files with a basic setup of your chosen libraries. + +For example, the following with configure the plugin `Acme.Example` with tailwind and create `plugins/acme/example/assets/src/acme-example.css` with a tailwind setup. + +```bash +php artisan vite:config acme.example --tailwind --stubs +``` + +## Manual Vite configuration + +The Vite configuration file (`vite.config.mjs`) is a configuration file that manages the configuration of Laravel Vite itself. In conjunction with the `package.json` file that defines your dependencies, this file defines how Laravel Vite will compile your assets. + +For more information, you can review [the Laravel docs](https://laravel.com/docs/11.x/vite) or the [Vite docs](https://vitejs.dev/config/). + +Your `vite.config.mjs` file must include Vite as a requirement, and must also define the public path to the current directory, as follows: + +```js +import { defineConfig } from 'vite'; +import laravel from 'laravel-vite-plugin'; + +export default defineConfig({ + plugins: [ + laravel({ + input: [ + 'assets/src/css/example.css', + 'assets/src/js/example.js', + ], + refresh: { + paths: [ + './**/*.htm', + './**/*.block', + 'assets/**/*.css', + 'assets/**/*.js', + ] + }, + }), + ], +}); +``` + +### Paths + +When the `vite.config.mjs` file is evaluated, regardless of where you ran `vite:compile` from, the working directory is set to the parent directory of the `vite.config.mjs` file. That means that any relative paths used in the configuration will be relative to the current directory of the `vite.config.mjs` file. + +## Vite vs. Mix + +Vite works slightly differently to Mix, therefore this section documents the differences between the two and should help with anybody attempting to transition between the two. + +### Vite server + +When running `vite:watch`, Vite will create a new webserver hosted, by default, on port `5173`. If your environment is blocking specific ports, you must enable access to this port to use `vite:watch`. + +By default, the vite server runs in http only mode, this may lead you to getting mixed content warnings in your browser. If this causes problems for you please see [the official vite docs](https://vitejs.dev/config/server-options#server-https). + +### Loading Vite assets + +Vite does not compile assets to a specific path like mix, instead you must use the helper functions to render your html imports. + +The helper function takes 2 arguments, the first is a `array|string` of entry path(s). These entry paths must exist in the inputs of your `vite.config.js`. The second argument is the "package" you wish to load these entry points from, i.e. `theme-example` or `acme.plugin`. + +- In `twig` this helper can be called via: + + ```twig + {{ vite(['assets/css/example.css', 'assets/js/example.js'], 'acme.plugin') }} + ``` + +- In `php` the `Vite` class offers a method for generating the imports: + + ```php + \System\Classes\Vite::tags(['assets/css/example.css', 'assets/js/example.js'], 'acme.plugin') + ``` + +- With the `AssetMaker` trait (i.e. in backend controllers, forms, etc.): + + ```php + $this->addVite(['assets/css/example.css'], 'acme.plugin'); + // The second param here is not required, Winter will attempt to guess the plugin based on the current namespace + $this->addVite(['assets/css/example.css']); + ``` + +## Commands + +### Install Node dependencies + +```bash +php artisan vite:install [-p ] [--npm ] +``` + +The `vite:install` command will install Node dependencies for all registered Vite packages. + +This command will add each registered package to the `workspaces.packages` property of your root `package.json` file and then run and display the results of `npm install` from your project root to install all of the dependencies for all of the registered packages at once. + +You can optionally provide a `-p` or `--package` flag to install dependencies for one or more packages. To define multiple packages, simply add more `-p` flags to the end of the command. + +If the command is run with a `-p` or `--package` flag and the provided package name is not already registered and the name matches a valid module, plugin, or theme package name (modules are prefixed with `module-$moduleDirectory`, themes are prefixed with `theme-$themeDirectory`, and plugins are simply `Author.Plugin`) then a `vite.config.mjs` file will be automatically generated for that package and will be included in future runs of any vite commands through the [automatic registration](#automatic-registration) feature. + +The `--npm` flag can also be provided if you have a custom path to the `npm` program. If this is not provided, the system will try to guess where `npm` is located. + +### List registered Vite packages + +```bash +php artisan vite:list [--json] +``` + +The `vite:list` command will list all registered Vite packages found in the Winter installation. This is useful for determining if your plugin or theme is correctly registered. + +The command will list all packages, as well as the directory for the asset and the configuration file that has been defined during registration. + +A json formatted list of packages can be printed by specifying the `--json` flag. + +### Compile a Vite packages + +```bash +php artisan vite:compile [-p ] [-f|--production] [-- ] +``` + +The `vite:compile` command compiles all registered Vite packages, running each package through Laravel Vite for compilation. + +By specifying the `-p` flag, you can compile one or more selected packages. To define multiple packages, simply add more `-p` flags to the end of the command. + +The `--no-progress` flag can be added in order to suppress the vite progress output. Useful if you want to only view the webpack output. + +By default, all packages are built in "development" mode. If you wish to compile in "production" mode, which may include more optimisations for production sites, add the `-f` or `--production` flag to the command. + +The command will generate a report of all compiled files and their final size once complete. + +If you wish to pass extra options to the Webpack CLI, for special cases of compilation, you can add `--` to the end of the command, followed by [any parameters](https://webpack.js.org/api/cli/) as per the Webpack CLI options. + +### Watch a Vite package + +```bash +php artisan vite:watch [-f|--production] [-- ] +``` + +The `vite:watch` command is similar to the `vite:compile` command, except that it remains active and watches for any changes made to files that would be affected by your compilation. When any changes are made, a compile is automatically executed. This is useful for development in allowing you to quickly make changes and review them in your browser. + +With this command, only one package can be provided and watched at any one time. diff --git a/console/asset-compilation.md b/console/asset-compilation.md index 21f9ebbb..6057f690 100644 --- a/console/asset-compilation.md +++ b/console/asset-compilation.md @@ -1,4 +1,4 @@ -# Asset Compilation (Mix) +# Asset Compilation ## Introduction @@ -16,304 +16,33 @@ Registering for asset compilation through Mix is very easy. Automatic registrati ### Automatic registration -By default, Winter will scan all available and enabled modules, plugins and themes for the presence of a `winter.mix.js` file under each extension's root folder (i.e. `modules/system/winter.mix.js`, `plugins/myauthor/myplugin/winter.mix.js`, or `themes/mytheme/winter.mix.js`). +By default, Winter will scan all available and enabled modules, plugins and themes for the presence of a config file from a supported compiler under each extension's root folder (i.e. `modules/system/config_file.js`, `plugins/myauthor/myplugin/config_file.js`, or `themes/mytheme/config_file.js`). -If the `winter.mix.js` file is found, it will be automatically registered as a package with an automatically generated package name, and will show up when running the Mix commands. Most of the time, this should be all you need to do in order to get started with Laravel Mix asset compilation in Winter CMS. +If the config file is found, it will be automatically registered as a package with an automatically generated package name, and will show up when running the applicable compiler's commands. Most of the time, this should be all you need to do in order to get started with one of the asset compilers in Winter CMS. -### Registering plugins +The currently supported config files are: -To register frontend assets to be compiled through Mix in your plugin, simply return an array with the package names as the keys and the package paths relative to the plugin's directory as the values to register from your [`Plugin.php`](../plugin/registration) registration file's `registerMixPackages()` method. See below example. +- `winter.mix.js` - for the Mix compiler. +- `vite.config.js` - for the Vite compiler. -```php -public function registerMixPackages() -{ - return [ - 'custom-package-name' => 'assets/js/build.mix.js', - ]; -} -``` - -### Registering themes - -Registration of asset compilation of themes is even easier, and can be done by adding a `mix` definition to your [theme information file](../themes/development#theme-information-file) (`theme.yaml`). - -```yaml -name: "Winter CMS Demo" -description: "Demonstrates the basic concepts of the frontend theming." -author: "Winter CMS" -homepage: "https://wintercms.com" -code: "demo" - -mix: - : winter.mix.js -``` - -The `mix` definition takes any number of registered packages as a YAML object, with the key being the name of the package as a kebab-case string and the location of your `winter.mix.js` file relative to the theme's root directory. - -For example, if you want to register two packages called `demo-theme-style` and `demo-theme-shop` located in the assets folder, you would use the following definition: - -```yaml -name: "Winter CMS Demo" -description: "Demonstrates the basic concepts of the frontend theming." -author: "Winter CMS" -homepage: "https://wintercms.com" -code: "demo" - -mix: - demo-theme-style: assets/style/winter.mix.js - demo-theme-shop: assets/shop/winter.mix.js -``` - -## Mix configuration - -The Mix configuration file (`winter.mix.js`) is a configuration file that manages the configuration of Laravel Mix itself. In conjunction with the `package.json` file that defines your dependencies, this file defines how Laravel Mix will compile your assets. - -You can [review examples](https://laravel-mix.com/docs/6.0/examples) or the [full Mix API](https://laravel-mix.com/docs/6.0/api) at the [Laravel Mix website](https://laravel-mix.com). - -Your `winter.mix.js` file must include Mix as a requirement, and must also define the public path to the current directory, as follows: - -```js -const mix = require('laravel-mix'); - -// For assets in the current directory -// mix.setPublicPath(__dirname); - -// For assets in a /assets subdirectory -mix.setPublicPath(__dirname + '/assets'); - -// Your mix configuration below -``` - -### Paths - -When the `winter.mix.js` file is evaluated, regardless of where you ran `mix:compile` from, the working directory is set to the parent directory of the `winter.mix.js` file. That means that any relative paths used in the configuration will be relative to the current directory of the `winter.mix.js` file. - ->**NOTE:** Winter's [path symbols](../services/helpers#path-symbols) are also supported in the `winter.mix.js` file. - -## Examples - -Here are some examples of installing common frontend libraries for use with the asset compilation. - -### Tailwind CSS - -For themes that wish to use Tailwind CSS, include the `tailwindcss`, `postcss` and `autoprefixer` dependencies in your `package.json` file. - -```bash -# Inside the project root folder -npm install --save-dev tailwindcss postcss autoprefixer - -# Run the Tailwind initialisation -npx tailwindcss init -``` +### Supported Asset Compilers -This will create a Tailwind configuration file (`tailwind.config.js`) inside your theme that you may [configure](https://tailwindcss.com/docs/installation) to your specific theme's needs. +Winter CMS supports the following: -Then, add a `winter.mix.js` configuration file that will compile Tailwind as needed: +- [Laravel Mix](./asset-compilation-mix.md). +- [Vite (with Laravel HRM installed)](./asset-compilation-vite.md). -```js -const mix = require('laravel-mix'); -mix.setPublicPath(__dirname); - -// Render Tailwind style -mix.postCss('assets/css/base.css', 'assets/css/theme.css', [ - require('postcss-import'), - require('tailwindcss'), -]); -``` - -In the example above, we have a base CSS file that contains the Tailwind styling - `assets/css/base.css` - that will compile to a final compiled CSS file in `assets/css/theme.css`. - -Your theme will now be ready for Tailwind CSS development. - -### Alpine JS - -For themes that wish to use Alpine JS, include the `alpinejs` dependency in your theme's `package.json` file. - -```bash -# Run this inside the theme's directory (i.e. myproject/themes/mytheme) -npm install alpinejs -``` - -You will need to update your Mix assets by running `php artisan mix:update` from the project root folder after the installation is complete. - -Import Alpine into your theme script bundle (for example, stored at `themes/mytheme/assets/src/js/scripts.js`), and initialize it like so: - -```js -import Alpine from 'alpinejs' -window.Alpine = Alpine -Alpine.start() -``` - -The `window.Alpine = Alpine` is optional, but is nice to have for flexibility by making `Alpine` globally accessible via JavaScript, for situations like tinkering with Alpine from the devtools or using Alpine inline in your theme files. - -Then, update your `winter.mix.js` configuration file that will compile Alpine as needed: - -```js -const mix = require('laravel-mix'); -mix.setPublicPath(__dirname); - -mix - // other mix commands - .js('assets/src/js/scripts.js', 'assets/dist/js/app.js'); -``` - -In the example above, we compile the theme script bundle that contains Alpine initialization - `assets/src/js/scripts.js` - into a final, compiled build at `assets/dist/js/app.js`. - -Your theme will now be ready to use Alpine JS by simply including the build in your theme's HTML: - -```html - -``` - -### Vue - -If you want to use [Vue 3](https://vuejs.org/) in your project, either in the backend or in a component or theme, you can follow these steps. - -First, define Vue as a dependency in your plugin's `package.json`: - -``` - "name": "myauthor-myplugin", - "private": true, - "version": "1.0.0", - "dependencies": { - "vue": "^3.2.41" - } -``` - -Run `php artisan mix:install` to install Vue and the dependencies that Vue requires. - -Then, add a `winter.mix.js` configuration file to your plugin directory. This will build a specific entry point file, in this case `assets/src/js/myplugin.js` and create a built version of your Vue app as `assets/dist/js/myplugin.js`. - -```js -const mix = require('laravel-mix'); -mix.setPublicPath(__dirname); -mix - // compile javascript assets for plugin - .js('assets/src/js/myplugin.js', 'assets/dist/js').vue({ version: 3 }) -``` - -Next you can create your Vue source files in your plugin's assets directory. Mix supports rendering of [single-file components](https://vuejs.org/guide/scaling-up/sfc.html), allowing you to define the template, scripting and styling all in one file. - -```js -// assets/src/js/myplugin.js - -import { createApp } from 'vue' -import Welcome from './components/Welcome' - -const myPlugin = createApp({}) - -myPlugin.component('welcome', Welcome) - -myPlugin.mount('[data-vue-app="myPlugin"]') -``` - -```js -// assets/src/js/components/Welcome.vue - - - - -``` - -Now if you comple your assets in the project root with `php artisan mix:compile`, Mix will create your compiled and built Vue component as a JS file. - -Next in the your controller's template file (eg. controllers/myvuecontroller/index.php) you can include the generated `myplugin.js` file, and render the content in the div with the `data-vue-app="myPlugin"` attribute: - -```html -
- -
- - -``` - -## Commands - -### Install Node dependencies - -```bash -php artisan mix:install [-p ] [--npm ] -``` - -The `mix:install` command will install Node dependencies for all registered Mix packages. - -This command will add each registered package to the `workspaces.packages` property of your root `package.json` file and then run and display the results of `npm install` from your project root to install all of the dependencies for all of the registered packages at once. - -You can optionally provide a `-p` or `--package` flag to install dependencies for one or more packages. To define multiple packages, simply add more `-p` flags to the end of the command. - -If the command is run with a `-p` or `--package` flag and the provided package name is not already registered and the name matches a valid module, plugin, or theme package name (modules are prefixed with `module-$moduleDirectory`, themes are prefixed with `theme-$themeDirectory`, and plugins are simply `Author.Plugin`) then a `winter.mix.js` file will be automatically generated for that package and will be included in future runs of any mix commands through the [automatic registration](#automatic-registration) feature. - -The `--npm` flag can also be provided if you have a custom path to the `npm` program. If this is not provided, the system will try to guess where `npm` is located. - -### Update Node dependencies - -```bash -php artisan mix:update [-p ] [--npm ] -``` - -The `mix:update` command will update Node dependencies for all registered Mix packages. - -This command operates very similar to `mix:install`, except that it only updates previously installed packages. This allows you to keep dependencies up to date, especially in the case of security fixes or breaking updates from your Node dependencies. - -Please see the `mix:install` documentation for the available arguments and options. - -### List registered Mix packages - -```bash -php artisan mix:list [--json] -``` - -The `mix:list` command will list all registered Mix packages found in the Winter installation. This is useful for determining if your plugin or theme is correctly registered. - -The command will list all packages, as well as the directory for the asset and the configuration file that has been defined during registration. - -A json formatted list of packages can be printed by specifying the `--json` flag. - -### Compile a Mix packages - -```bash -php artisan mix:compile [-p ] [-f|--production] [-- ] -``` - -The `mix:compile` command compiles all registered Mix packages, running each package through Laravel Mix for compilation. - -By specifying the `-p` flag, you can compile one or more selected packages. To define multiple packages, simply add more `-p` flags to the end of the command. - -The `--no-progress` flag can be added in order to suppress the mix progress output. Useful if you want to only view the webpack output. - -By default, all packages are built in "development" mode. If you wish to compile in "production" mode, which may include more optimisations for production sites, add the `-f` or `--production` flag to the command. - -The command will generate a report of all compiled files and their final size once complete. - -If you wish to pass extra options to the Webpack CLI, for special cases of compilation, you can add `--` to the end of the command, followed by [any parameters](https://webpack.js.org/api/cli/) as per the Webpack CLI options. - -### Watch a Mix package - -```bash -php artisan mix:watch [-f|--production] [-- ] -``` - -The `mix:watch` command is similar to the the `mix:compile` command, except that it remains active and watches for any changes made to files that would be affected by your compilation. When any changes are made, a compile is automatically executed. This is useful for development in allowing you to quickly make changes and review them in your browser. - -With this command, only one package can be provided and watched at any one time. +For more information on these compilers, see the links above. ### Run a package script ```bash -php artisan mix:run