├── .gitattributes
├── README.md
├── aliases.md
├── api.md
├── autoloading.md
├── autoprefixer.md
├── browsersync.md
├── cli.md
├── concatenation-and-minification.md
├── copying-files.md
├── css.md
├── event-hooks.md
├── examples.md
├── extending-mix.md
├── extract.md
├── faq.md
├── hot-module-replacement.md
├── index.md
├── installation.md
├── legacy-node-polyfills.md
├── less.md
├── license.md
├── livereload.md
├── mixjs.md
├── os-notifications.md
├── postcss.md
├── quick-webpack-configuration.md
├── sass.md
├── stylus.md
├── upgrade.md
├── url-rewriting.md
├── versioning.md
├── vue.md
├── what-is-mix.md
└── workflow.md
/.gitattributes:
--------------------------------------------------------------------------------
1 | /.github export-ignore
2 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | 
4 |
5 |
6 |
7 | # Laravel Mix Documentation
8 |
9 | You can find the online version of the Laravel Mix documentation at [https://laravel-mix.com/docs](https://laravel-mix.com/docs).
10 | The source code of the laravel-mix.com website it self can be found [here](https://github.com/mvdnbrk/laravel-mix.com).
11 |
12 | ## Sponsors
13 |
14 |
15 |
16 | 
17 |
18 |
19 |
20 |
21 |
22 | 
23 |
24 |
25 |
26 |
27 |
28 | 
29 |
30 |
31 |
32 | ## Credits
33 |
34 | - [Jeffrey Way](https://github.com/jeffreyway)
35 | - [Mark van den Broek](https://github.com/mvdnbrk)
36 | - [All Contributors](../../contributors)
37 |
38 | ## License
39 |
40 | The MIT License (MIT). Please see [License File](license.md) for more information.
41 |
--------------------------------------------------------------------------------
/aliases.md:
--------------------------------------------------------------------------------
1 | # Aliases
2 |
3 | - [Aliasing Paths](#aliasing-paths)
4 | - [Aliasing Existing Modules](#aliasing-existing-modules)
5 |
6 | Mix offers the ability to configure aliases that get expanded when importing files.
7 | It supports aliasing specific paths and whole modules.
8 |
9 | ### Aliasing Paths
10 |
11 | Path aliases are useful when you want to include files from a particular directory but do so from many others without repeatedly writing things like `../file.js` and `../../../file.js`.
12 |
13 | Mix can assist in this regard. Consider the following example:
14 |
15 | ```js
16 | mix.alias({
17 | '@': path.join(__dirname, 'resources/js')
18 | });
19 | ```
20 |
21 | This allows one to write `import { useFoo } from "@/Hooks` and it'll be expanded to `import { useFoo } from "/absolute/path/to/your/project/resources/js/Hooks`.
22 |
23 | ### Aliasing Existing Modules
24 |
25 | In addition to aliasing paths you can also alias the definition of an entire module.
26 | For example, when importing Vue 3.x we'd prefer to import the ESM bundler version which is more suitable for tree-shaking.
27 |
28 | This is achieved by the following snippet:
29 |
30 | ```js
31 | mix.alias({
32 | vue$: path.join(__dirname, 'node_modules/vue/dist/vue.esm-bundler.js')
33 | });
34 | ```
35 |
36 | Here's another, more complete example of aliasing a common path and many dependencies to their ESM equivalents (instead of their default CommonJS imports):
37 |
38 | ```js
39 | mix.alias({
40 | '@': path.join(__dirname, 'resources/js'),
41 | d3$: path.join(__dirname, 'node_modules/d3/index.js'),
42 | vue$: path.join(__dirname, 'node_modules/vue/dist/vue.esm-bundler.js'),
43 | luxon$: path.join(__dirname, 'node_modules/luxon/src/luxon.js'),
44 | dompurify$: path.join(
45 | __dirname,
46 | 'node_modules/dompurify/dist/purify.es.js'
47 | ),
48 | easymde$: path.join(__dirname, 'node_modules/easymde/src/js/easymde.js'),
49 | 'billboard.js$': path.join(
50 | __dirname,
51 | 'node_modules/billboard.js/dist/billboard.esm.js'
52 | )
53 | });
54 | ```
55 |
--------------------------------------------------------------------------------
/api.md:
--------------------------------------------------------------------------------
1 | # The Mix API
2 |
3 | Below, you'll find the full Mix API. Out of the box, Mix supports a wide array of frameworks and preprocessors.
4 |
5 | The methods below assume that you've imported `mix` at the top of your `webpack.mix.js` file, like so:
6 |
7 | ```js
8 | let mix = require('laravel-mix');
9 | ```
10 |
11 | ### `.js(src, output)`
12 |
13 | Bundle your JavaScript assets.
14 |
15 | ```js
16 | mix.js('src/file.js', 'dist/file.js');
17 | ```
18 |
19 | ### `.ts(src, dist)`
20 |
21 | Bundle your TypeScript assets.
22 |
23 | ```js
24 | mix.ts('src/file.ts', 'dist/file.js');
25 | ```
26 |
27 | ### `.vue(options?)`
28 |
29 | Add support for Vue single file components.
30 |
31 | ```js
32 | mix.js('src/file.js', 'dist/file.js').vue();
33 | ```
34 |
35 | Vue 2 and 3 differ slightly in how they should be bundled. Mix will do its best to check which
36 | version you currently have installed; however, if you wish, you can be explict.
37 |
38 | ```js
39 | mix.js('src/file.js', 'dist/file.js').vue({ version: 2 });
40 | ```
41 |
42 | ### `.react()`
43 |
44 | Add support for React compilation.
45 |
46 | ```js
47 | mix.js('src/file.js', 'dist/file.js').react();
48 | ```
49 |
50 | ### `.preact()`
51 |
52 | Add support for Preact compilation.
53 |
54 | ```js
55 | mix.js('src/file.js', 'dist/file.js').preact();
56 | ```
57 |
58 | ### `.coffee(src, output)`
59 |
60 | Preprocess CoffeeScript files.
61 |
62 | ```js
63 | mix.coffee('src/file.coffee', 'dist/file.js');
64 | ```
65 |
66 | ### `.postCss(src, output, plugins[]?)`
67 |
68 | Compile PostCss files.
69 |
70 | ```js
71 | mix.postCss('src/file.css', 'dist/file.css', [
72 | require('precss')() // your PostCss plugins
73 | ]);
74 | ```
75 |
76 | ### `.sass(src, output, sassPluginOptions?)`
77 |
78 | Compile Sass files.
79 |
80 | ```js
81 | mix.sass('src/file.scss', 'dist/file.css');
82 | ```
83 |
84 | ### `.less(src, output)`
85 |
86 | Compile Less files.
87 |
88 | ```js
89 | mix.less('src/file.less', 'dist/file.css');
90 | ```
91 |
92 | ### `.stylus(src, output)`
93 |
94 | Compile Stylus files.
95 |
96 | ```js
97 | mix.stylus('src/file.styl', 'dist/file.css');
98 | ```
99 |
100 | ### `.extract(vendors?, output?)`
101 |
102 | Use webpack code-splitting to extract any or all vendor dependencies into their own files.
103 |
104 | ```js
105 | mix.js('src/file.js', 'dist/file.js').extract(['vue']);
106 | ```
107 |
108 | When no dependency is provided, Mix will bundle all imported dependencies from the `node_modules/` directory to a `vendor.js` file.
109 |
110 | ```js
111 | mix.js('src/file.js', 'dist/file.js').extract();
112 | ```
113 |
114 | You can customize the output of the extraction using the output param. It would be relative to the public path.
115 |
116 | ```js
117 | mix.js('src/file.js', 'dist/file.js').vue().extract(['vue'], 'js/v.js');
118 | mix.setPublicPath('public').js('src/file.js', 'dist/file.js').extract('js/v.js');
119 | ```
120 |
121 | ### `.version(files[]?)`
122 |
123 | Version all compiled assets by appending a unique hash to every file within `mix-manifest.json`. This is useful for cache-busting purposes.
124 |
125 | ```js
126 | mix.js('src/file.js', 'dist/file.js').version();
127 | ```
128 |
129 | If using Laravel, refer to its global `mix()` helper function for dynamically accessing this hashed file path.
130 |
131 | ```html
132 |
133 | ```
134 |
135 | ### `.sourceMaps(generateForProduction?, devType?, productionType?)`
136 |
137 | Generate JavaScript source maps.
138 |
139 | ```js
140 | mix.js('src/file.js', 'dist/file.js').sourceMaps();
141 | ```
142 |
143 | ### `.browserSync(domain)`
144 |
145 | Monitor files for changes and update the browser without requiring a manual page refresh.
146 |
147 | ```js
148 | mix.js('...').browserSync('your-domain.test');
149 | ```
150 |
151 | ### `.setPublicPath(path)`
152 |
153 | Set the path to where all public assets should be compiled to. For non-Laravel projects, always include a call to this method.
154 |
155 | ```js
156 | mix.setPublicPath('dist');
157 | ```
158 |
159 | ### `.webpackConfig(config)`
160 |
161 | Merge a webpack configuration object with the one Mix has generated. This can be useful when you want to drop down a level and manipulate the webpack configuration directly.
162 |
163 | ```js
164 | mix.webpackConfig({
165 | plugins: [new SomeWebpackPlugin()]
166 | });
167 | ```
168 |
169 | ### `.override(fn(webpackConfig))`
170 |
171 | Register a handler for _after_ the webpack configuration has been fully constructed. This is your last chance to override Mix's configuration before the compiling begins.
172 |
173 | ```js
174 | mix.override(webpackConfig => {
175 | webpackConfig.module.rules.push({
176 | test: /\.extension$/,
177 | use: []
178 | });
179 | });
180 | ```
181 |
182 | ### `.dump()`
183 |
184 | Log the generated webpack configuration to the console. This is temporary command that may be useful for debugging purposes.
185 |
186 | ```js
187 | mix.dump();
188 | ```
189 |
190 | ### `.autoload(libraries)`
191 |
192 | Make a module available as a variable in every other module required by webpack. If you're working with a particular plugin or library that depends upon a global variable, such as jQuery, this command may prove useful.
193 |
194 | ```js
195 | mix.autoload({
196 | jquery: ['$', 'window.jQuery']
197 | });
198 | ```
199 |
200 | ### `.before(callback)`
201 |
202 | Run the given callback function before the webpack compilation begins.
203 |
204 | ```js
205 | mix.before(() => {
206 | fs.copySync('path/from', 'path/to');
207 | });
208 | ```
209 |
210 | If your script is asynchronous, you must return a promise to ensure that Mix waits for it to complete before beginning the compilation.
211 |
212 | ```js
213 | mix.before(() => {
214 | return new Promise(resolve => {
215 | setTimeout(resolve, 2000);
216 | });
217 | });
218 | ```
219 |
220 | ### `.after(callback)`
221 |
222 | Run the given callback function after the webpack compilation has completed.
223 |
224 | ```js
225 | mix.after(webpackStats => {
226 | console.log('Compilation complete');
227 | });
228 | ```
229 |
230 | ### `.options(options)`
231 |
232 | Merge and override Mix's default configuration settings. Refer to this package's `src/config.js` file for a full list of settings that can be overridden.
233 |
234 | Below is a brief list of the most common overrides.
235 |
236 | ```js
237 | mix.options({
238 | processCssUrls: false,
239 | postCss: [],
240 | terser: {},
241 | autoprefixer: {},
242 | legacyNodePolyfills: false
243 | });
244 | ```
245 |
--------------------------------------------------------------------------------
/autoloading.md:
--------------------------------------------------------------------------------
1 | # Autoloading
2 |
3 | - [Basic Usage](#basic-usage)
4 |
5 | Webpack offers the necessary functionality to make any module available as a variable within every other module required by webpack.
6 |
7 | If you're working with a particular plugin or library that depends upon a global variable - jQuery being the most common example - `mix.autoload()` may prove useful to you.
8 |
9 | ### Basic Usage
10 |
11 | Consider the following example:
12 |
13 | ```js
14 | mix.autoload({
15 | jquery: ['$', 'window.jQuery']
16 | });
17 | ```
18 |
19 | This snippet declares that every time webpack encounters the `$` or `window.jQuery` variables, it should swap them out with `var $ = require('jquery')`.
20 |
--------------------------------------------------------------------------------
/autoprefixer.md:
--------------------------------------------------------------------------------
1 | # Autoprefixer
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Set Custom Autoprefixer Options](#set-custom-autoprefixer-options)
5 | - [Disable Autoprefixer](#disable-autoprefixer)
6 |
7 | By default, Mix will pipe all of your CSS through the popular [Autoprefixer PostCSS plugin](https://github.com/postcss/autoprefixer). As such, you are free to use the latest CSS 3 syntax with the understanding that we'll apply any necessary browser-prefixes automatically.
8 |
9 | ### Basic Usage
10 |
11 | Assuming your CSS entry file is:
12 |
13 | ```css
14 | /* src/app.css */
15 |
16 | @keyframes foo {
17 | to {
18 | background: red;
19 | }
20 | }
21 |
22 | #selector {
23 | animation: foo 2s;
24 | }
25 | ```
26 |
27 | If you add CSS compilation to your `webpack.mix.js` file...
28 |
29 |
30 | ```js
31 | // webpack.mix.js
32 |
33 | mix.css('src/app.css', 'dist');
34 | ```
35 |
36 | The generated output file will automatically add any necessary CSS browser-prefixes, based on the latest global browser usage statistics.
37 |
38 | ```css
39 | /* dist/app.css */
40 |
41 | @-webkit-keyframes foo {
42 | to {
43 | background: red;
44 | }
45 | }
46 |
47 | @keyframes foo {
48 | to {
49 | background: red;
50 | }
51 | }
52 |
53 | #selector {
54 | -webkit-animation: foo 2s;
55 | animation: foo 2s;
56 | }
57 | ```
58 |
59 | ### Set Custom Autoprefixer Options
60 |
61 | The default settings should be fine in most scenarios, however, if you need to tweak the underlying
62 | Autoprefixer configuration, reach for `mix.options()`.
63 |
64 | ```js
65 | mix.postCss('src/app.css', 'dist')
66 | .options({
67 | autoprefixer: { remove: false }
68 | });
69 | ```
70 |
71 | ### Disable Autoprefixer
72 |
73 | If you instead wish to disable autoprefixing entirely, set `autoprefixer` to `false`.
74 |
75 | ```js
76 | mix.postCss('src/app.css', 'dist')
77 | .options({ autoprefixer: false });
78 | ```
79 |
80 | All underlying Autoprefixer options [may be reviewed here](https://github.com/postcss/autoprefixer#options).
81 |
--------------------------------------------------------------------------------
/browsersync.md:
--------------------------------------------------------------------------------
1 | # Browsersync
2 |
3 | Browsersync will automatically monitor your files for changes, and inject any changes into the browser - all without requiring a manual refresh.
4 | You can enable support by calling the `mix.browserSync()` command, like so:
5 |
6 | ```js
7 | mix.browserSync('my-domain.test');
8 | ```
9 |
10 | If you need to pass configuration options to the underlying Browsersync, instead pass an object.
11 |
12 | ```js
13 | mix.browserSync({
14 | proxy: 'my-domain.test',
15 | });
16 | ```
17 |
18 | All Browsersync configuration options may be reviewed on the [Browsersync](https://browsersync.io/docs/options/) website.
19 |
--------------------------------------------------------------------------------
/cli.md:
--------------------------------------------------------------------------------
1 | # The Mix CLI
2 |
3 | - [Compiling in a Local Environment](#compiling-in-a-local-environment)
4 | - [Watch Assets for Changes](#watch-assets-for-changes)
5 | - [Polling](#polling)
6 | - [Hot Module Replacement](#hot-module-replacement)
7 | - [Compiling for Production](#compiling-for-production)
8 | - [Customize the Mix Configuration Path](#customize-the-mix-configuration-path)
9 | - [Pass Options to Webpack-CLI](#pass-options-to-webpack-cli)
10 |
11 |
12 | As part of Mix v6, you'll find a new CLI that simplifies your build scripts.
13 |
14 | ### Compiling in a Local Environment
15 |
16 |
17 | To build assets for development, reach for the `npx mix` command. Mix will then read your `webpack.mix.js` configuration file, and compile your assets.
18 |
19 | ```bash
20 | npx mix
21 | ```
22 |
23 | #### Watch Assets for Changes
24 |
25 | Particularly for larger projects, compilation can take a bit of time. For this reason, it's highly recommended that you instead leverage webpack's ability to watch your filesystem for changes. The `npx mix watch` command will handle this for you. Now, each time you update a file, Mix will automatically recompile the file and rebuild your bundle.
26 |
27 | ```bash
28 | npx mix watch
29 | ```
30 |
31 | #### Polling
32 |
33 | In certain situations, webpack may not automatically detect changes. An example of this is when you're on an NFS volume inside virtualbox. If this is a problem, pass the `--watch-options-poll` option directly to webpack-cli to turn on manual polling.
34 |
35 | ```bash
36 | npx mix watch -- --watch-options-poll=1000
37 | ```
38 |
39 | Of course, you can add this to a build script within your `package.json` file.
40 |
41 | #### Hot Module Replacement
42 |
43 | Hot module replacement is a webpack featured that gives supporting modules the ability to "live update" in certain situations. A live-update is when your application refreshes without requiring a page reload. In fact, this is what powers Vue's live updates when developing. To turn this feature on, include the `--hot` flag.
44 |
45 | ```bash
46 | npx mix watch --hot
47 | ```
48 |
49 | ### Compiling for Production
50 |
51 | When it comes time to build your assets for a production environment, Mix will set the appropriate webpack options, minify your source code, and optionally version your assets based on your Mix configuration file (`webpack.mix.js`). To build assets for production, include the `--production` flag - or the alias `-p` - to the Mix CLI. Mix will take care of the rest!
52 |
53 | ```bash
54 | npx mix --production
55 | ```
56 |
57 | #### Customize the Mix Configuration Path
58 |
59 | You may customise the location of your `webpack.mix.js` file by using the `--mix-config` option. For example, if you wish to load your `webpack.mix.js` file from a nested `build` directory, here's how:
60 |
61 | ```bash
62 | npx mix --mix-config=build/webpack.mix.js --production
63 | ```
64 |
65 | ### Pass Options to Webpack-CLI
66 |
67 | If you end any `mix` call with two dashes (`--`), anything after it will be passed through to webpack-cli. For example, you can pass environment variables using webpack-cli's `--env` option:
68 |
69 | ```bash
70 | npx mix -- --env foo=bar
71 | ```
72 |
--------------------------------------------------------------------------------
/concatenation-and-minification.md:
--------------------------------------------------------------------------------
1 | # Concatenation and Minification
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Concatenate All Files in a Directory](#concatenate-all-files-in-a-directory)
5 | - [Concatenate All Matching Files in a Directory](#concatenate-all-matching-files-in-a-directory)
6 | - [Concatenate an Array of Files](#concatenate-an-array-of-files)
7 | - [Concatenate Scripts and Apply Babel Compilation](#concatenate-scripts-and-apply-babel-compilation)
8 | - [File Minification](#file-minification)
9 | - [Minify a Single File](#minify-a-single-file)
10 | - [Minify an Array of File](#minify-an-array-of-file)
11 |
12 | Laravel Mix and webpack should take care of all the necessary module bundling and minification for you. However, you may have lingering legacy code or vendor libraries that need to remain separate from your core webpack bundle. Not a problem.
13 |
14 | For basic file concatenation and minification, Mix has you covered.
15 |
16 | ### Basic Usage
17 |
18 | Consider the following Mix configuration file.
19 |
20 | ```js
21 | mix.combine(['one.js', 'two.js'], 'merged.js');
22 | ```
23 |
24 | This instructs Mix to merge - or concatenate - `one.js` and `two.js` into a single file, called `merged.js`. As always, during development, that merged file will remain uncompressed. However, when building for production, `merged.js` will of course be minified.
25 |
26 | > {tip} If it reads better to you, `mix.scripts()` and `mix.styles()` are aliases for `mix.combine()`.
27 |
28 | #### Concatenate All Files in a Directory
29 |
30 | ```js
31 | mix.combine('path/to/dir', 'all-files.js');
32 |
33 | // or:
34 |
35 | mix.scripts('path/to/dir', 'all-files.js');
36 | ```
37 |
38 | #### Concatenate All Matching Files in a Directory
39 |
40 | ```js
41 | mix.combine('path/to/dir/*.css', 'all-files.css');
42 |
43 | // or:
44 |
45 | mix.styles('path/to/dir/*.css', 'all-files.css');
46 | ```
47 |
48 | #### Concatenate an Array of Files
49 |
50 | ```js
51 | mix.combine([
52 | 'path/to/dir/*.css',
53 | 'path/to/second/dir/*.css'
54 | ], 'all-files.css');
55 | ```
56 |
57 | #### Concatenate Scripts and Apply Babel Compilation
58 |
59 | If you need to concatenate and then compile JavaScript files that have been written with the latest JavaScript syntax, you may either set the third argument of `mix.combine()` to `true`, or instead call `mix.babel()`. Other than the Babel compilation, both commands are identical.
60 |
61 | ```js
62 | // Both of these are identical.
63 | mix.combine(['one.js', 'two.js'], 'merged.js', true);
64 | mix.babel(['one.js', 'two.js'], 'merged.js');
65 | ```
66 |
67 | ### File Minification
68 |
69 | Similarly, you may also minify one or more files with the `mix.minify()` command.
70 |
71 | There are a few things worth noting here:
72 |
73 | 1. `mix.minify()` will create a companion `*.min.{extension}` file. So minifying `app.js` will generate `app.min.js` within the same directory.
74 | 2. As always, minification will only take place during a production build.
75 | 3. There is no need to call `mix.combine(['one.js', 'two.js'], 'merged.js').minify('merged.js');`Just stick with the single `mix.combine()` call. It'll take care of both.
76 |
77 | > **Important**: Minification is only available for CSS and JavaScript files. The minifier will not understand any other provided file type.
78 |
79 | #### Minify a Single File
80 |
81 | ```js
82 | mix.minify('path/to/file.js');
83 | ```
84 |
85 | #### Minify an Array of File
86 |
87 | ```js
88 | mix.minify(['this/one.js', 'and/this/one.js']);
89 | ```
90 |
--------------------------------------------------------------------------------
/copying-files.md:
--------------------------------------------------------------------------------
1 | # Copying Files
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Copy a Single File](#copy-a-single-file)
5 | - [Copy Multiple Files](#copy-multiple-files)
6 | - [Copy a Directory](#copy-a-directory)
7 | - [Copy Files With the Given Extension](#copy-files-with-the-given-extension)
8 | - [Exclude an Extension From Being Copied](#exclude-an-extension-from-being-copied)
9 |
10 | ### Basic Usage
11 |
12 | There might be times when, as part of your build, you need to copy one or more files from one location to another. Mix's `copy()` command makes this a cinch.
13 |
14 | #### Copy a Single File
15 |
16 | ```js
17 | mix.copy('node_modules/foo/bar.css', 'public/css');
18 | ```
19 |
20 | #### Copy Multiple Files
21 |
22 | ```js
23 | mix.copy([
24 | 'src/foo/one.css',
25 | 'src/bar/two.css'
26 | ], 'public/css');
27 | ```
28 |
29 | #### Copy a Directory
30 |
31 | A common usecase for this is when you wish to move a set of fonts, installed through NPM, to your public directory.
32 |
33 | ```js
34 | mix.copy('node_modules/vendor/fonts', 'public');
35 | ```
36 |
37 | If it provides more clarity, `mix.copyDirectory()` is an alias for `mix.copy()`. The following is identical to the previous example.
38 |
39 | ```js
40 | mix.copyDirectory('node_modules/vendor/fonts', 'public');
41 | ```
42 |
43 | Please note that, when providing a directory path as the first argument, the output will retain the original directory structure. If you wish to "flatten" it, provide a wildcard search.
44 |
45 | ```js
46 | mix.copyDirectory('path/to/dir/**', 'public/output');
47 | ```
48 |
49 | #### Copy Files With the Given Extension
50 |
51 | ```js
52 | mix.copy('vendor/lib/tests/**/*.php', 'tests');
53 | ```
54 |
55 | #### Exclude an Extension From Being Copied
56 |
57 | ```js
58 | mix.copy('tests/**/!(*.js)', 'public/foo');
59 | ```
60 |
61 | The above will copy all files except for those that end in `.js`.
62 |
--------------------------------------------------------------------------------
/css.md:
--------------------------------------------------------------------------------
1 | # General CSS Compilation
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Advanced Usage](#advanced-usage)
5 |
6 | ### Basic Usage
7 |
8 | Mix provides the `mix.css()` command for basic CSS compilation. Here's an example that imports the Normalize CSS library and adds a single rule.
9 |
10 | ```css
11 | /* src/app.css */
12 |
13 | @import '~normalize.css/normalize.css';
14 |
15 | body {
16 | color: red;
17 | }
18 | ```
19 |
20 | We can now add CSS compilation to our `webpack.mix.js` file, like so:
21 |
22 | ```js
23 | // webpack.mix.js
24 | let mix = require('laravel-mix');
25 |
26 | mix.css('src/app.css', 'dist');
27 | ```
28 |
29 | Run webpack with `npx mix` and you'll find a `/dist/app.css` file that contains the full Normalize library, as well as your `body` rule.
30 |
31 | Easy!
32 |
33 | ### Advanced Usage
34 |
35 | As you'll find in the next section, `mix.css()` is an alias for `mix.postCss()`. This means you have full access to the entire PostCSS plugin ecosystem as part of your compilation.
36 |
37 |
--------------------------------------------------------------------------------
/event-hooks.md:
--------------------------------------------------------------------------------
1 | # Event Hooks
2 |
3 | - [Run a Function Before Webpack Compiles](#run-a-function-before-webpack-compiles)
4 | - [Run a Function After Webpack Compiles](#run-a-function-after-webpack-compiles)
5 |
6 | ### Run a Function Before Webpack Compiles
7 |
8 | In some scenarios, you may need to execute a piece of logic **before** your compilation begins. Perhaps you need to copy a directory or move a file. The `mix.before()` function allows for this.
9 |
10 | ```js
11 | mix.before(() => {
12 | console.log('I will be logged before the compilation begins.');
13 | });
14 | ```
15 |
16 | If the logic you're executing is asynchronous, be sure to return a `Promise` from your callback function, like so:
17 |
18 | ```js
19 | mix.before(stats => {
20 | return new Promise(
21 | resolve => setTimeout(resolve, 2000)
22 | );
23 | });
24 | ```
25 |
26 | Mix will not begin its compilation until all `before` hooks have fully resolved. As such, for this example the compilation would begin after two seconds.
27 |
28 | ### Run a Function After Webpack Compiles
29 |
30 | If, on the other hand, you need to execute a piece of logic **after** webpack has completed its compilation, reach for the `mix.after()` method - or its alias, `mix.then()`.
31 |
32 | ```js
33 | mix.js('src/app.js', 'dist')
34 | .after(stats => {
35 | // webpack compilation has completed
36 | });
37 | ```
38 |
39 | This callback function will be passed a webpack `Stats` object. As an example, let's log a list of all compiled assets.
40 |
41 | ```js
42 | mix.js('resources/assets/js/app.js', 'public/js').then(stats => {
43 | console.log(Object.keys(stats.compilation.assets));
44 | });
45 | ```
46 |
47 | The official documentation for the `Stats` object [may be found here](https://github.com/webpack/docs/wiki/node.js-api#stats).
48 |
--------------------------------------------------------------------------------
/examples.md:
--------------------------------------------------------------------------------
1 | # Examples
2 |
3 | ### Compile Modern JavaScript
4 |
5 | ```js
6 | mix.js('src/app.js', 'js');
7 | ```
8 |
9 | ### Compile Sass
10 |
11 | ```js
12 | mix.sass('src/app.scss', 'css');
13 | ```
14 |
15 | ### Compile JavaScript and Sass
16 |
17 | ```js
18 | mix.js('src/app.js', 'js')
19 | .sass('src/app.scss', 'css');
20 | ```
21 |
22 | ### Compile JavaScript and Set the Output Base Directory
23 |
24 | ```js
25 | mix.js('src/app.js', 'js')
26 | .sass('src/app.scss', 'css')
27 | .setPublicPath('dist');
28 | ```
29 |
30 | ### Compile CSS With PostCSS Plugins
31 |
32 | ```js
33 | mix.postCss('src/app.css', 'dist', [
34 | require('postcss-custom-properties')
35 | ]);
36 | ```
37 |
38 | ### Compile JavaScript With File Versioning
39 |
40 | ```js
41 | mix.js('src/app.js', 'js')
42 | .version();
43 | ```
44 |
45 | Once compiled, the hash can be retrieved from your `mix-manifest.json` file.
46 |
47 | ### Compile JavaScript With Support for Vue Single File Components
48 |
49 | ```js
50 | mix.js('src/app.js', 'js')
51 | .vue();
52 | ```
53 |
54 | ### Compile JavaScript and Set an Explicit Vue Version
55 |
56 | ```js
57 | mix.js('src/app.js', 'js')
58 | .vue({ version: 3 });
59 | ```
60 |
61 | ### Extract Vue Single File Component CSS to its Own File
62 |
63 | ```js
64 | mix.js('src/app.js', 'js')
65 | .vue({ extractStyles: true });
66 | ```
67 |
68 | ### Extract Vue Single File Component CSS to a named File
69 |
70 | ```js
71 | mix.js('src/app.js', 'js')
72 | .vue({ extractStyles: 'css/vue-styles.css' });
73 | ```
74 |
75 | ### Compile JavaScript With Support for React
76 |
77 | ```js
78 | mix.js('src/app.js', 'js')
79 | .react();
80 | ```
81 |
82 | ### Compile JavaScript and Extract Lodash to its Own File
83 |
84 | ```js
85 | mix.js('src/app.js', 'js')
86 | .extract(['lodash']);
87 | ```
88 |
89 | ### Compile JavaScript and Extract All Vendor Dependencies
90 |
91 | ```js
92 | mix.js('src/app.js', 'js')
93 | .extract();
94 | ```
95 |
96 | ### Enable Source Maps
97 |
98 | ```js
99 | mix.js('src/app.js', 'js')
100 | .sourceMaps();
101 | ```
102 |
103 | ### Make jQuery Available to Every Module
104 |
105 | ```js
106 | mix.js('src/app.js', 'js')
107 | .autoload({
108 | jquery: ['$', 'window.jQuery']
109 | });
110 | ```
111 |
112 | ### Trigger Browsersync Page Refreshes When in Watch Mode
113 |
114 | ```js
115 | mix.js('src/app.js', 'js')
116 | .sass('src/app.scss', 'css')
117 | .browserSync('http://your-app.test');
118 | ```
119 |
120 | Then run `npx mix watch`.
121 |
122 | ### Load an Environment File Key
123 |
124 | ```js
125 | // .env
126 | MIX_SOME_KEY=yourpublickey
127 | ```
128 |
129 | Only keys in your `.env` file that begin with "MIX_" will be loaded.
130 |
131 | ```js
132 | // webpack.mix.js
133 | mix.js('src/app.js', 'js')
134 | ```
135 |
136 | ```js
137 | // src/app.js
138 | console.log(
139 | process.env.MIX_SOME_KEY
140 | ); // yourpublickey
141 | ```
142 |
143 |
--------------------------------------------------------------------------------
/extending-mix.md:
--------------------------------------------------------------------------------
1 | # Extending Mix
2 |
3 | - [Build a Simple Plugin](#build-a-simple-plugin)
4 | - [Component Classes](#component-classes)
5 | - [The Component Interface](#the-component-interface)
6 | - [Plugin Usage](#plugin-usage)
7 |
8 | The very component-based system that Mix uses behind the scenes to build its API is also
9 | accessible to you - whether to extend Mix for your own personal projects, or to distribute as a package to the rest of the world.
10 |
11 | ### Build a Simple Plugin
12 |
13 | ```js
14 | // webpack.mix.js;
15 | let mix = require('laravel-mix');
16 |
17 | mix.extend('foo', function(webpackConfig, ...args) {
18 | // The webpack configuration object.
19 | console.log(webpackConfig);
20 |
21 | // All arguments passed to mix.foo();
22 | console.log(args); // ['some-foo']
23 | });
24 |
25 | // Trigger your new plugin.
26 | mix.foo('some-value');
27 | ```
28 |
29 | In the example above, notice how `mix.extend()` accepts two parameters:
30 |
31 | 1. The name that should be used when triggering your component.
32 | 2. A callback function or class that registers and organizes the necessary webpack logic. Behind the scenes, Mix will call this function after the underlying webpack configuration object has been constructed.
33 | This will give you a chance to insert or override any necessary webpack-specific settings.
34 |
35 | ### Component Classes
36 |
37 | While a simple callback function may be useful for quick extensions, in most scenarios,
38 | you'll likely want to build a full component class, like so:
39 |
40 | ```js
41 | // foo.js
42 | let mix = require('laravel-mix');
43 |
44 | class FooPlugin {
45 | register(val) {
46 | console.log('mix.foo() was called with ' + val);
47 | }
48 |
49 | webpackConfig(config) {
50 | //
51 | }
52 | }
53 |
54 | mix.extend('foo', new FooPlugin());
55 | ```
56 |
57 | ```js
58 | // webpack.mix.js
59 |
60 | let mix = require('laravel-mix');
61 |
62 | require('./foo');
63 |
64 | mix.foo('bar'); // "mix.foo() was called with bar"
65 | ```
66 |
67 | When preparing Mix extensions, you'll typically need to trigger a handful of instructions. For instance:
68 |
69 | 1. Install _these_ dependencies.
70 | 2. Add this rule/loader to the webpack config.
71 | 3. Include this webpack plugin.
72 | 4. Override this part of the webpack configuration entirely.
73 | 5. Add this config to Babel.
74 | 6. etc.
75 |
76 | Any of these operations are a cinch with Mix's component system.
77 |
78 | ### The Component Interface
79 |
80 | - **name**: What should be used as the method name, when calling the component. (Defaults to camelCased version of the component class name.)
81 | - **dependencies**: List all npm dependencies that should be installed by Mix.
82 | - **register**: When your component is called, all user parameters will instantly be passed to this method.
83 | - **boot**: Boot the component. This method is triggered after the user's webpack.mix.js file has fully loaded.
84 | - **webpackEntry**: Append to Mix's webpack entry object.
85 | - **webpackRules**: Rules to be merged with the underlying webpack rules.
86 | - **webpackPlugins**: Plugins to be merged with the underlying webpack plugins array.
87 | - **webpackConfig**: Override the underlying webpack configuration.
88 | - **babelConfig**: Additional Babel configuration that should be merged with Mix's defaults.
89 |
90 | Below is a dummy component that will give you a better idea of how you'll construct your own components. For more examples, [refer to the very
91 | components that Mix uses behind the scenes](https://github.com/JeffreyWay/laravel-mix/tree/master/src/components).
92 |
93 | ```js
94 | class Example {
95 | /**
96 | * The optional name to be used when called by Mix.
97 | * Defaults to the class name, lowercased.
98 | *
99 | * Ex: mix.example();
100 | *
101 | * @return {String|Array}
102 | */
103 | name() {
104 | // Example:
105 | // return 'example';
106 | // return ['example', 'alias'];
107 | }
108 |
109 | /**
110 | * All npm dependencies that should be installed by Mix.
111 | *
112 | * @return {Array}
113 | */
114 | dependencies() {
115 | // Example:
116 | // return ['typeScript', 'ts'];
117 | }
118 |
119 | /**
120 | * Register the component.
121 | *
122 | * When your component is called, all user parameters
123 | * will be passed to this method.
124 | *
125 | * Ex: register(src, output) {}
126 | * Ex: mix.yourPlugin('src/path', 'output/path');
127 | *
128 | * @param {*} ...params
129 | * @return {void}
130 | *
131 | */
132 | register() {
133 | // Example:
134 | // this.config = { proxy: arg };
135 | }
136 |
137 | /**
138 | * Boot the component. This method is triggered after the
139 | * user's webpack.mix.js file has processed.
140 | */
141 | boot() {
142 | // Example:
143 | // if (Config.options.foo) {}
144 | }
145 |
146 | /**
147 | * Append to the underlying webpack entry object.
148 | *
149 | * @param {Entry} entry
150 | * @return {void}
151 | */
152 | webpackEntry(entry) {
153 | // Example:
154 | // entry.add('foo', 'bar');
155 | }
156 |
157 | /**
158 | * Rules to be merged with the underlying webpack rules.
159 | *
160 | * @return {Array|Object}
161 | */
162 | webpackRules() {
163 | // Example:
164 | // return {
165 | // test: /\.less$/,
166 | // loaders: ['...']
167 | // });
168 | }
169 |
170 | /*
171 | * Plugins to be merged with the underlying webpack plugins array.
172 | *
173 | * @return {Array|Object}
174 | */
175 | webpackPlugins() {
176 | // Example:
177 | // return new webpack.ProvidePlugin(this.aliases);
178 | }
179 |
180 | /**
181 | * Override the underlying webpack configuration.
182 | *
183 | * @param {Object} webpackConfig
184 | * @return {void}
185 | */
186 | webpackConfig(webpackConfig) {
187 | // Example:
188 | // webpackConfig.resolve.extensions.push('.ts', '.tsx');
189 | }
190 |
191 | /**
192 | * Babel config to be merged with Mix's defaults.
193 | *
194 | * @return {Object}
195 | */
196 | babelConfig() {
197 | // Example:
198 | // return { presets: ['@babel/preset-react'] };
199 | }
200 | }
201 | ```
202 |
203 | Note that each of the methods in the example above are optional. In certain situations, your component may only need to add a webpack loader and/or tweak the Babel configuration that Mix uses. No problem. Omit the rest of the interface.
204 |
205 | ```js
206 | class Example {
207 | webpackRules() {
208 | return {
209 | test: /\.test$/,
210 | loaders: []
211 | };
212 | }
213 | }
214 | ```
215 |
216 | Now, when Mix constructs the underlying webpack configuration, your `.test` rule will be included as part of the generated `webpackConfig.module.rules` array.
217 |
218 | ### Plugin Usage
219 |
220 | Once you've constructed or installed your desired component, simply require it from your `webpack.mix.js` file,
221 | and you're all set to go.
222 |
223 | ```js
224 | // example.js
225 |
226 | let mix = require('laravel-mix');
227 |
228 | class Example {
229 | webpackRules() {
230 | return {
231 | test: /\.test$/,
232 | loaders: []
233 | };
234 | }
235 | }
236 |
237 | mix.extend('example', new Example());
238 | ```
239 |
240 | ```js
241 | // webpack.mix.js
242 |
243 | let mix = require('laravel-mix');
244 |
245 | require('./example');
246 |
247 | mix.js('src', 'output')
248 | .example();
249 | ```
250 |
--------------------------------------------------------------------------------
/extract.md:
--------------------------------------------------------------------------------
1 | # Code Splitting
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Customize the Runtime Chunk Path](#customize-the-runtime-chunk-path)
5 | - [The Manifest File](#the-manifest-file)
6 | - [Multiple Extractions](#multiple-extractions)
7 | - [Fallback Extractions](#fallback-extractions)
8 | - [Extractions Using Regular Expressions](#extractions-using-regular-expressions)
9 | - [Custom Extraction Tests](#custom-extraction-tests)
10 | - [The Manifest File](#the-manifest-file)
11 |
12 | Bundling your JavaScript into a single file has one big downside: each time you change a minor detail in your application code, you must bust the browser cache. Even if you only change a single variable name, users will still need to re-download that generated file.
13 |
14 | One solution is to isolate, or extract, your vendor libraries into their own file(s).
15 |
16 | - **Application Code**: `app.js`
17 | - **Vendor Libraries**: `vendor.js`
18 | - **Manifest \(webpack Runtime\)**: `manifest.js`
19 |
20 | This will result in a significantly smaller `app.js` file. Now, using the above example, if you change a variable name, only the application-specific JavaScript will need to be re-downloaded. The larger vendor libraries - `vendor.js` - may remain cached.
21 |
22 | ### Basic Usage
23 |
24 | ```js
25 | // 1. Extract all node_modules vendor libraries into a vendor.js file.
26 | mix.extract();
27 |
28 | // 2. Only extract the Vue and jQuery libraries (if used) into a vendor.js file.
29 | mix.extract(['vue', 'jquery']);
30 |
31 | // 3. Extract Vue and jQuery (if used) to custom-vendor-name.js.
32 | mix.extract(['vue', 'jquery'], 'custom-vendor-name.js');
33 | ```
34 |
35 | If you don't pass an array of npm libraries to the `extract` method, Mix will extract _all_ imported libraries from your project's `node_modules` directory. This is a useful default; however, if you need to be explicit, pass an array of the specific libraries that should be extracted.
36 |
37 | Once you compile your code - `npx mix` - you'll find three new files: `app.js`, `vendor.js`, and `manifest.js`. You may reference these at the bottom of your HTML.
38 |
39 | ```html
40 |
41 |
42 |
43 | ```
44 |
45 | While it's true that we're now importing three scripts instead of one, the benefit is improved long-term caching of vendor code that rarely changes. Further, HTTP2 makes the cost of importing multiple scripts a non-issue.
46 |
47 | ### Customize the Runtime Chunk Path
48 |
49 | By default, the runtime chunk (`manifest.js`) is generated next to your JS assets.
50 |
51 | However, the path can easily be customized, relative to the public path:
52 |
53 | ```js
54 | mix.options({ runtimeChunkPath: 'custom' });
55 |
56 | // The `manifest.js` file will now be saved to `public/custom/manifest.js`
57 | ```
58 |
59 | If you instead prefer the public path, use `.`.
60 |
61 | ```js
62 | mix.js('resources/app.js', 'public/js');
63 | mix.options({ runtimeChunkPath: '.' });
64 |
65 | // The `manifest.js` file will now be saved to `public/manifest.js`
66 | ```
67 |
68 | ### Multiple Extractions
69 |
70 | You may call `mix.extract(['library1', 'library2'])` multiple times with different arguments to extract different sets of libraries into separate files.
71 |
72 | ```js
73 | mix.extract(['vue', 'lodash-es'], 'vendor~utils-1.js');
74 | mix.extract(['jquery', 'axios'], 'vendor~utils-2.js');
75 |
76 | // `vendor~utils-1.js` will contain Vue and Lodash
77 | // `vendor~utils-2.js` will contain jQuery and Axios
78 | ```
79 |
80 | ### Fallback Extractions
81 |
82 | A call to `mix.extract()` may be paired with one or more calls to `mix.extract(['library1', 'library2'], 'file.js')` and all libraries not extracted into specific files will be saved to `vendor.js`.
83 |
84 | ```js
85 | mix.extract(['vue', 'lodash-es'], 'vendor~utils-1.js');
86 | mix.extract(['jquery', 'axios'], 'vendor~utils-2.js');
87 | mix.extract();
88 |
89 | // `vendor~utils-1.js` will contain Vue and Lodash
90 | // `vendor~utils-2.js` will contain jQuery and Axios
91 | // `vendor.js` will contain all other used libraries from node_modules
92 | ```
93 |
94 | #### Extractions Using Regular Expressions
95 |
96 | It is now possible to match libraries by a regular expression. This is useful for libraries split into many modules/packages, like D3. To leverage this feature, pass an object to `mix.extract()`.
97 |
98 | ```js
99 | mix.extract({
100 | // If you don't specify a location, it defaults to `vendor.js`
101 | to: 'js/vendor-d3.js',
102 |
103 | // This can be an array of strings or a regular expression
104 | libraries: /d3|d3-[a-z0-9-]+/
105 | });
106 | ```
107 |
108 | #### Custom Extraction Tests
109 |
110 | If you require more control over how modules are extracted, include a `test` function that receives the webpack module object and returns a boolean.
111 |
112 | ```js
113 | mix.extract({
114 | to: 'js/vendor-core-js.js',
115 | test(mod) {
116 | return /core-js/.test(mod.nameForCondition());
117 | }
118 | });
119 | ```
120 |
121 | ### The Manifest File
122 |
123 | You might still be confused by that third `manifest.js` file. Webpack compiles with a small bit of run-time code to assist with its job. When not using `mix.extract()`, this code is invisible to you and lives inside your bundle file. However, if we need to split our code, that runtime code must "live" somewhere. As such, Laravel Mix will extract it to its own file.
124 |
--------------------------------------------------------------------------------
/faq.md:
--------------------------------------------------------------------------------
1 | # Frequently Asked Questions
2 |
3 | ### Does this tool require that I use Laravel?
4 |
5 | No. It has awareness of Laravel, but it can be used for any project. Just be sure to explicitly set the path to your project's `public` or `dist` directory, like so:
6 |
7 | ```js
8 | mix.setPublicPath('dist');
9 | ```
10 |
11 | This tells Mix the basic directory where all of your assets should be compiled to.
12 |
13 | ### My code isn't being minified.
14 |
15 | Minification will only be performed when your `NODE_ENV` is set to _production_. By default, this mode is set to development.
16 |
17 | ```bash
18 | npx mix
19 | ```
20 |
21 | If you're ready to build for a production environment, add the `--production` flag, like so:
22 |
23 | ```bash
24 | npx mix --production
25 | ```
26 |
27 | ### I'm using a VM, and webpack isn't picking up my file changes.
28 |
29 | If you're running `npx mix` through a VM, you may find that file changes are not picked up by webpack. If that's the case, consider configuring webpack to **poll** your filesystem for changes, like so:
30 |
31 | ```js
32 | npx mix watch --poll
33 | ```
34 |
35 | ### Why is it saying that an image in my CSS file can't be found in `node_modules`?
36 |
37 | Imagine that you have a relative path to an asset that doesn't exist in your `resources/sass/app.scss` file.
38 |
39 | ```css
40 | body {
41 | background: url('../img/example.jpg');
42 | }
43 | ```
44 |
45 | When referencing a relative path, always think in terms of the current file. As such, webpack will look one level up for `resources/assets/img/example.jpg`. If it can't find it, it'll then begin searching for the file location, including within the massive `node_modules` directory. If it still can't be found, you'll receive the error:
46 |
47 | ```
48 | ERROR Failed to compile with 1 errors
49 |
50 | This dependency was not found in node_modules:
51 | ```
52 |
53 | You have two possible solutions:
54 |
55 | 1. Make sure that `resources/assets/img/example.jpg` exists.
56 | 2. Add the following to your `webpack.mix.js` file to disable CSS url() processing.
57 |
58 | ```
59 | mix.sass('resources/assets/sass/app.scss', 'public/css')
60 | .options({
61 | processCssUrls: false
62 | });
63 | ```
64 |
65 | This is particularly useful for legacy projects where your folder structure is already exactly as you desire.
66 |
67 | ### My mix-manifest.json file shouldn't be in the project root.
68 |
69 | If you're not using Laravel, your `mix-manifest.json` file will be dumped into the project root. If you need to change this, call `mix.setPublicPath('dist/');`, and your manifest file will now correctly be saved to the `dist` directory.
70 |
71 | ### Can I autoload modules with Mix and webpack?
72 |
73 | Yes. Through its `ProvidePlugin` plugin, webpack allows for this very functionality. A common use-case for this is when we need jQuery to be available to all of your modules. Here's a webpack-specific example of how you might accomplish this.
74 |
75 | ```js
76 | new webpack.ProvidePlugin({
77 | $: 'jquery',
78 | jQuery: 'jquery'
79 | });
80 |
81 | // in a module
82 | $('#item'); // <= just works
83 | jQuery('#item'); // <= just works
84 | // $ is automatically set to the exports of module "jquery"
85 | ```
86 |
87 | Of course, Mix provides an API on top of webpack to make this sort of autoloading a cinch.
88 |
89 | ```js
90 | mix.autoload({
91 | jquery: ['$', 'window.jQuery', 'jQuery'], // more than one
92 | moment: 'moment' // only one
93 | });
94 | ```
95 |
96 | Above, we're effectively saying, "When webpack comes across the `$` or `window.jQuery` or `jQuery` symbols, replace it with the exported jQuery module."
97 |
98 | ### Why am I seeing a "Vue packages version mismatch" error?
99 |
100 | If, upon updating your dependencies, your compile fails with the message:
101 |
102 | ```
103 | Module build failed: Error:
104 |
105 | Vue packages version mismatch:
106 |
107 | * vue@2.5.13
108 | * vue-template-compiler@2.5.15
109 | ```
110 |
111 | This means your `vue` and `vue-template-compiler` dependencies are out of sync. Per Vue 2's instructions, the version number for both of these dependencies must be identical. Update as needed to fix the problem:
112 |
113 | ```bash
114 | npm update vue
115 |
116 | // or
117 |
118 | npm install vue@2.5.15
119 | ```
120 |
121 | ### I'm having trouble updating/installing Mix.
122 |
123 | Unfortunately, there are countless reasons why your dependencies may not be installing properly. A common root relates to an ancient version of Node (`node -v`) and npm (`npm -v`) installed. As a first step, visit http://nodejs.org and update those.
124 |
125 | Otherwise, often, it's related to a faulty lock file that needs to be deleted. Give this series of commands a try to install everything from scratch:
126 |
127 | ```bash
128 | rm -rf node_modules
129 | rm package-lock.json yarn.lock
130 | npm cache clear --force
131 | npm install
132 | ```
133 |
--------------------------------------------------------------------------------
/hot-module-replacement.md:
--------------------------------------------------------------------------------
1 | # Hot Module Replacement
2 |
3 | - [Basic Usage in Laravel](#basic-usage-in-laravel)
4 |
5 | Where available, Laravel Mix provides seamless support for hot module replacement.
6 |
7 | > {tip} Hot Module Replacement \(or Hot Reloading\) allows you to, not just refresh the page when a piece of JavaScript is changed, but also maintain the current state of the component in the browser.
8 |
9 | Consider a simple counter component. When you press a button, the count goes up. Imagine that you click this button a number of times, and then update the component file. Normally,
10 | you'd need to refresh the page to reflect the changes. As such, the count would of course default back to its original state: 0. With hot reloading enabled, however, the webpage will refresh to
11 | reflect your change without requiring a page refresh. The current count will remain unchanged. This is the beauty of hot reloading!
12 |
13 | ### Basic Usage in Laravel
14 |
15 | Laravel and Mix work together to tuck away the necessary complexity required to get hot reloading up and running.
16 |
17 | From the command line, run `npx mix watch --hot` to boot up a Node server and monitor your bundle for changes. Next, load your Laravel app in the browser, as you normally would: perhaps `http://my-app.test`.
18 |
19 | The key to making hot reloading work within a Laravel application is ensuring that all script sources reference the Node server URL that we just booted up. This will be [http://localhost:8080](http://localhost:8080). Now you could of course manually update your HTML/Blade files, like so:
20 |
21 | ```html
22 |
23 | ...
24 |
25 |
26 | ```
27 |
28 | This would indeed work. Give it a try. Assuming you have some demo components to work with, try changing the state in the browser and then modifying the component's template. You should see your browser instantly refresh to reflect the change, without losing your state.
29 |
30 | However, it can be a burden - and risk - to manually change this URL back and forth for production deploys. To solve this, Laravel's `mix()` function will build up your script or stylesheet imports dynamically, and echo them out. Change the code snippet above to:
31 |
32 | ```html
33 |
34 |
35 |
36 |
37 |
38 | ```
39 |
40 | With this adjustment, Laravel will do the work for you. If you run `npx mix watch --hot` to enable hot reloading, the function will prepend the necessary `http://localhost:8080` base url. If, instead, you run `npx mix` or `npx mix watch`, it'll reference your domain as the base.
41 |
--------------------------------------------------------------------------------
/index.md:
--------------------------------------------------------------------------------
1 | - ## Overview
2 | - [Upgrade](/docs/{{version}}/upgrade)
3 | - [What is Mix?](/docs/{{version}}/what-is-mix)
4 | - [Installation](/docs/{{version}}/installation)
5 | - [Examples](/docs/{{version}}/examples)
6 | - [Laravel Quick Start](/docs/{{version}}/workflow)
7 | - [The Full Mix API](/docs/{{version}}/api)
8 | - [The Mix CLI](/docs/{{version}}/cli)
9 | - [FAQ](/docs/{{version}}/faq)
10 |
11 | - ## JavaScript
12 | - [JavaScript Bundling](/docs/{{version}}/mixjs)
13 | - [Vue Support](/docs/{{version}}/vue)
14 | - [File Versioning](/docs/{{version}}/versioning)
15 | - [Code Splitting](/docs/{{version}}/extract)
16 | - [Autoloading](/docs/{{version}}/autoloading)
17 | - [Hot Module Replacement](/docs/{{version}}/hot-module-replacement)
18 | - [Node Polyfills (Process/Buffer)](/docs/{{version}}/legacy-node-polyfills)
19 |
20 | - ## CSS
21 | - [General CSS Compilation](/docs/{{version}}/css)
22 | - [PostCSS Compilation](/docs/{{version}}/postcss)
23 | - [Sass Compilation](/docs/{{version}}/sass)
24 | - [Less Compilation](/docs/{{version}}/less)
25 | - [Stylus Compilation](/docs/{{version}}/stylus)
26 | - [Autoprefixing](/docs/{{version}}/autoprefixer)
27 | - [Relative URL Rewriting](/docs/{{version}}/url-rewriting)
28 |
29 | - ## Tasks
30 | - [Copy Files and Directories](/docs/{{version}}/copying-files)
31 | - [Concatenation and Minification](/docs/{{version}}/concatenation-and-minification)
32 |
33 | - ## Helpers and Configuration
34 | - [BrowserSync](/docs/{{version}}/browsersync)
35 | - [Aliases](/docs/{{version}}/aliases)
36 | - [OS Notifications](/docs/{{version}}/os-notifications)
37 | - [Custom Webpack Configuration](/docs/{{version}}/quick-webpack-configuration)
38 |
39 | - ## Plugin Development
40 | - [Extending Mix](/docs/{{version}}/extending-mix)
41 | - [Event Hooks](/docs/{{version}}/event-hooks)
42 |
43 | - ## Custom Recipes
44 | - [LiveReload](/docs/{{version}}/livereload)
45 |
46 | - ## License
47 | - [MIT](/docs/{{version}}/license)
48 |
--------------------------------------------------------------------------------
/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | - [Stand-Alone Projects](#stand-alone-projects)
4 | - [Laravel Projects](#laravel-projects)
5 |
6 | Though Laravel Mix was originally built for Laravel projects, it of course may be used for any type of application.
7 |
8 | ## Stand-Alone Projects
9 |
10 | ### Step 1. Install Mix
11 |
12 | Begin by installing Laravel Mix through NPM or Yarn.
13 |
14 | ```bash
15 | mkdir my-app && cd my-app
16 | npm init -y
17 | npm install laravel-mix --save-dev
18 | ```
19 |
20 | ### Step 2. Create a Mix Configuration File
21 |
22 | Next, create a Mix configuration file within the root of your new project.
23 |
24 | ```bash
25 | touch webpack.mix.js
26 | ```
27 |
28 | You should now have the following directory structure:
29 |
30 | - `node_modules/`
31 | - `package.json`
32 | - `webpack.mix.js`
33 |
34 | `webpack.mix.js` is your configuration layer on top of webpack. Most of your time will be spent here.
35 |
36 | ### Step 3. Define Your Compilation
37 |
38 | Open `webpack.mix.js` and add the following code:
39 |
40 | ```js
41 | // webpack.mix.js
42 |
43 | let mix = require('laravel-mix');
44 |
45 | mix.js('src/app.js', 'dist').setPublicPath('dist');
46 | ```
47 |
48 | At its core, Mix is an opinionated, fluent API on top of webpack. In the example above, we've instructed Mix to compile `src/app.js` and save it to the `dist/` directory. If you're working along, create `src/app.js` now, and populate it with a simple alert:
49 |
50 | ```js
51 | // src/app.js
52 | alert('hello world');
53 | ```
54 |
55 | Of course this is only a placeholder for your actual JavaScript code.
56 |
57 | ### Step 4. Compile
58 |
59 | We're now ready to bundle up our assets. Mix provides a command-line program called `mix` which triggers the appropriate webpack build. Give it a run now.
60 |
61 | ```bash
62 | npx mix
63 | ```
64 |
65 | Congrats! You've created your first bundle. Create an HTML file, load your script, and you'll see an alert when the page loads.
66 |
67 | ## Laravel Projects
68 |
69 | Laravel ships with everything you need to get started. Simply:
70 |
71 | - Install Laravel (`laravel new app`)
72 | - Run `npm install`
73 | - Visit your `webpack.mix.js file`, and get started!
74 |
--------------------------------------------------------------------------------
/legacy-node-polyfills.md:
--------------------------------------------------------------------------------
1 | # Node Polyfills (Process and Buffer)
2 |
3 | Webpack 5 no longer automatically includes polyfills for Node-specific objects like `Buffer` and `process`.
4 | However, it's possible that your project, or one of its dependencies, still requires access to these variables.
5 | If so, you can force Mix to include the necessary Node polyfills via the `legacyNodePolyfills` option.
6 |
7 | ```js
8 | mix.options({
9 | legacyNodePolyfills: true
10 | });
11 | ```
12 |
13 | Keep in mind that this might result in a slightly larger bundle.
14 | If possible, take the necessary steps to eventually remove these references from your front-end code and then turn off `legacyNodePolyfills` to reduce your bundle size.
15 |
--------------------------------------------------------------------------------
/less.md:
--------------------------------------------------------------------------------
1 | # Less Preprocessing
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Plugin Options](#plugin-options)
5 | - [Multiple Outputs](#multiple-outputs)
6 |
7 | ### Basic Usage
8 |
9 | Here's a quick example to get you started. Imagine that you have the following Less file that needs to be compiled to vanilla CSS.
10 |
11 | ```less
12 | // src/app.less
13 | @primary: grey;
14 |
15 | .app {
16 | background: @primary;
17 | }
18 | ```
19 |
20 | No problem. Let's add Less compilation to our `webpack.mix.js` file.
21 |
22 | ```js
23 | // webpack.mix.js
24 | let mix = require('laravel-mix');
25 |
26 | mix.less('src/app.less', 'dist');
27 | ```
28 |
29 | Compile this down as usual \(`npx mix`\), and you'll find a `/dist/app.css` file that contains:
30 |
31 | ```css
32 | .app {
33 | background: grey;
34 | }
35 | ```
36 |
37 | Easy!
38 |
39 | ### Plugin Options
40 |
41 | Behind the scenes, Laravel Mix of course defers to webpack's `less-loader` to load and compile your Less files.
42 | From time to time, you may need to override the default options that we pass to it. Use the third argument to `mix.less()` in these scenarios.
43 |
44 | ```js
45 | mix.less('src/app.less', 'dist', {
46 | lessOptions: {
47 | strictMath: true
48 | }
49 | });
50 | ```
51 |
52 | For a full list of supported options, please [refer to the webpack documentation](https://webpack.js.org/loaders/less-loader/#options) for `less-loader`.
53 |
54 | ### Multiple Outputs
55 |
56 | Should you need to compile more than one root file, you may call `mix.less()` as many as times as necessary. For each call, webpack will output a new file with the relevant contents.
57 |
58 | ```js
59 | mix.less('src/app.less', 'dist/') // creates 'dist/app.css'
60 | .less('src/forum.less', 'dist/'); // creates 'dist/forum.css'
61 | ```
62 |
--------------------------------------------------------------------------------
/license.md:
--------------------------------------------------------------------------------
1 | # MIT License
2 |
3 | Copyright (c) Jeffrey Way
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/livereload.md:
--------------------------------------------------------------------------------
1 | # LiveReload
2 |
3 | While Laravel Mix ships with Browsersync support out of the box, you may prefer to use LiveReload. LiveReload can automatically monitor your files for changes and refresh the page when a modification is detected.
4 |
5 | ### Step 1. Install webpack-livereload-plugin
6 |
7 | ```bash
8 | npm install webpack-livereload-plugin@1 --save-dev
9 | ```
10 |
11 | ### Step 2. Configure `webpack.mix.js`
12 |
13 | Add the following lines to the bottom of your webpack.mix.js:
14 |
15 | ```js
16 | var LiveReloadPlugin = require('webpack-livereload-plugin');
17 |
18 | mix.webpackConfig({
19 | plugins: [new LiveReloadPlugin()]
20 | });
21 | ```
22 |
23 | Although LiveReload works well with its defaults, a list of available plugin options may be reviewed [here](https://github.com/statianzo/webpack-livereload-plugin/blob/master/README.md).
24 |
25 | ### Step 3. Install LiveReload.js
26 |
27 | Finally, we need to install LiveReload.js. You may do so via the [LiveReload Chrome plugin](https://chrome.google.com/webstore/detail/livereload/jnihajbhpnppcggbcgedagnkighmdlei),
28 | or by adding the following code just before the closing ` ` tag within your layout file.
29 |
30 | ```blade
31 | @env('local')
32 |
33 | @endenv
34 | ```
35 |
36 | ### Step 4. Run the Dev Server
37 |
38 | ```bash
39 | npx mix watch
40 | ```
41 |
42 | Now, LiveReload will automatically monitor your files and refresh the page when necessary. Enjoy!
43 |
--------------------------------------------------------------------------------
/mixjs.md:
--------------------------------------------------------------------------------
1 | # JavaScript
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [TypeScript Support](#typescript-support)
5 |
6 | ### Basic Usage
7 |
8 | ```js
9 | mix.js('src/app.js', 'dist/app.js');
10 | ```
11 |
12 | With a single method call, Laravel Mix allows you to trigger a variety of powerful actions.
13 |
14 | - Compile the [latest JavaScript syntax](https://babeljs.io/docs/en/babel-preset-env).
15 | - Trigger hot module replacement (via the `npx mix watch --hot` command).
16 | - Enable tree-shaking (where supported) for smaller builds.
17 | - Automatically optimizate and minify, when building for production (`npx mix --production`).
18 |
19 | ```js
20 | let mix = require('laravel-mix');
21 |
22 | // 1. Compile src/app.js to dist/app.js
23 | mix.js('src/app.js', 'dist');
24 |
25 | // 2. Compile src/app.js to dist/foo.js
26 | mix.js('src/app.js', 'dist/foo.js');
27 |
28 | // 3. Merge and compile multiple scripts to dist/app.js
29 | mix.js(['src/app.js', 'src/another.js'], 'dist/app.js');
30 |
31 | // 4. Compile src/app.js to dist/app.js and src/forum.js to dist/forum.js
32 | mix.js('src/app.js', 'dist/').js('src/forum.js', 'dist/');
33 | ```
34 |
35 | ### Typescript Support
36 |
37 | Laravel Mix also ships with basic Typescript support. Simply update your `mix.js()` call to `mix.ts()`, and then use the exact same set of arguments.
38 |
39 | ```js
40 | mix.ts('src/app.ts', 'dist');
41 | ```
42 |
43 | Of course, you'll still want to handle any TypeScript-specific tweaks like creating a `tsconfig.json` file and installing [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped), but everything else should be taken care of.
44 |
--------------------------------------------------------------------------------
/os-notifications.md:
--------------------------------------------------------------------------------
1 | # OS Notifications
2 |
3 | By default, Laravel Mix is configured to display a system notification for each compilation. This allows you to quickly determine if you have any errors that need addressing.
4 | However, if you find this annoying or not appropriate for your needs, they can of course be disabled, like so:
5 |
6 | ```js
7 | mix.disableNotifications();
8 | ```
9 |
10 | Goodbye notifications.
11 |
12 | As a slight tweak, you can instead disable success messages exclusively.
13 |
14 | ```js
15 | mix.disableSuccessNotifications();
16 | ```
17 |
--------------------------------------------------------------------------------
/postcss.md:
--------------------------------------------------------------------------------
1 | # PostCSS Preprocessing
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Add PostCSS Plugins](#add-postcss-plugins)
5 | - [Apply Plugins Globally](#apply-plugins-globally)
6 | - [Use a PostCSS Config File](#use-a-postcss-config-file)
7 |
8 | ### Basic Usage
9 |
10 | Imagine that you have the following CSS file that needs to be compiled and piped through a series of PostCSS plugins. In the example below,
11 | we'll need to pull in the `postcss-custom-properties` or `postcss-preset-env` PostCSS plugin.
12 |
13 | ```css
14 | :root {
15 | --some-color: red;
16 | }
17 |
18 | .example {
19 | color: var(--some-color);
20 | }
21 | ```
22 |
23 | > {tip} You can view a list of all available PostCSS plugins [here](https://github.com/postcss/postcss#plugins).
24 |
25 | No problem. First, install the PostCSS plugin through npm.
26 |
27 | ```bash
28 | npm install postcss-custom-properties --save-dev
29 | ```
30 |
31 | Next, add PostCSS compilation to your `webpack.mix.js` file, like so:
32 |
33 | ```js
34 | // webpack.mix.js
35 |
36 | let mix = require('laravel-mix');
37 |
38 | mix.postCss('src/app.css', 'dist');
39 | ```
40 |
41 | > {tip} `mix.postCss()` and `mix.css()` are aliases. Both commands work for all examples in this section.
42 |
43 | ### Add PostCSS Plugins
44 |
45 | At this point, we're using PostCSS, but we haven't yet instructed Mix to pull in the `postcss-custom-properties` plugin. We can add an array
46 | of plugins as the third argument to `mix.postCss()`, like so:
47 |
48 | ```js
49 | // webpack.mix.js
50 |
51 | let mix = require('laravel-mix');
52 |
53 | mix.postCss('src/app.css', 'dist', [
54 | require('postcss-custom-properties')
55 | ]);
56 | ```
57 |
58 | #### Apply Plugins Globally
59 |
60 | The above example will **exclusively** pipe `src/app.css` through the `postcss-custom-properties` plugin. However, if you're compiling multiple CSS entrypoints, it can be cumbersome to duplicate your PostCSS plugins array for each call.
61 |
62 | ```js
63 | // webpack.mix.js
64 |
65 | let mix = require('laravel-mix');
66 |
67 | mix.postCss('src/one.css', 'dist', [
68 | require('postcss-custom-properties')
69 | ]);
70 |
71 | mix.postCss('src/two.css', 'dist', [
72 | require('postcss-custom-properties')
73 | ]);
74 |
75 | mix.postCss('src/three.css', 'dist', [
76 | require('postcss-custom-properties')
77 | ]);
78 | ```
79 |
80 | Instead, you can apply your desired PostCSS plugins globally by either using `mix.options()`...
81 |
82 | ```js
83 | mix.postCss('src/one.css', 'dist')
84 | .postCss('src/two.css', 'dist')
85 | .postCss('src/three.css', 'dist');
86 |
87 | mix.options({
88 | postCss: [
89 | require('postcss-custom-properties')
90 | ]
91 | });
92 | ```
93 |
94 | ...or by creating a `postcss.config.js` file.
95 |
96 | #### Use a PostCSS Config File
97 |
98 | If you create a `postcss.config.js` file within the root of your project, Mix will automatically detect and import it.
99 |
100 | ```js
101 | // postcss.config.js
102 |
103 | module.exports = {
104 | plugins: [
105 | require('postcss-preset-env')
106 | ]
107 | }
108 | ```
109 |
110 | With this adjustment, your `webpack.mix.js` file can return to:
111 |
112 | ```js
113 | // webpack.mix.js
114 |
115 | let mix = require('laravel-mix');
116 |
117 | mix.postCss('src/app.css', 'dist');
118 | ```
119 |
120 | When you're ready, compile your code as usual (`npx mix`), and you'll find a `/dist/app.css` file that contains:
121 |
122 | ```css
123 | .example {
124 | color: red;
125 | }
126 | ```
127 |
128 | Perfect!
129 |
--------------------------------------------------------------------------------
/quick-webpack-configuration.md:
--------------------------------------------------------------------------------
1 | # Webpack Configuration
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Passing a Callback Function](#passing-a-callback-function)
5 |
6 | In certain cases, it may prove easier to drop down a level and override the underlying webpack configuration directly. Mix provides the `mix.webpackConfig()` command to allow for this.
7 |
8 | ### Basic Usage
9 |
10 | ```js
11 | // 1. Pass an object.
12 | mix.webpackConfig({
13 | plugins: []
14 | });
15 |
16 | // 2. Pass a callback function.
17 | mix.webpackConfig(webpack => {
18 | return {
19 | plugins: []
20 | };
21 | });
22 | ```
23 |
24 | As an example, perhaps you want to provide an array of modules that should be automatically loaded by webpack. We'll use Laravel Spark as an example.
25 |
26 | ```js
27 | mix.webpackConfig({
28 | resolve: {
29 | modules: [
30 | 'node_modules',
31 | path.resolve(__dirname, 'vendor/laravel/spark/resources/assets/js')
32 | ]
33 | }
34 | });
35 | ```
36 |
37 | The object passed to `mix.webpackConfig()` will now smartly be merged with Mix's generated webpack configuration.
38 |
39 | ### Passing a Callback Function
40 |
41 | You may alternatively access webpack and all of its properties by passing a callback function.
42 |
43 | ```js
44 | mix.webpackConfig(webpack => {
45 | return {
46 | plugins: [
47 | new webpack.ProvidePlugin({
48 | //
49 | })
50 | ]
51 | };
52 | });
53 | ```
54 |
--------------------------------------------------------------------------------
/sass.md:
--------------------------------------------------------------------------------
1 | # Sass Preprocessing
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Plugin Options](#plugin-options)
5 | - [Multiple Outputs](#multiple-outputs)
6 |
7 | ### Basic Usage
8 |
9 | Here's a quick example to get you started. Imagine that you have the following Sass file that needs to be compiled to vanilla CSS.
10 |
11 | ```scss
12 | // src/app.scss
13 | $primary: grey;
14 |
15 | .app {
16 | background: $primary;
17 | }
18 | ```
19 |
20 | No problem. Let's add Sass compilation to our `webpack.mix.js` file.
21 |
22 | ```js
23 | // webpack.mix.js
24 | let mix = require('laravel-mix');
25 |
26 | mix.sass('src/app.scss', 'dist');
27 | ```
28 |
29 | > {tip} For Sass compilation, you may freely use the `.sass` and `.scss` syntax styles.
30 |
31 | Compile this down as usual \(`npx mix`\), and you'll find a `/dist/app.css` file that contains:
32 |
33 | ```css
34 | .app {
35 | background: grey;
36 | }
37 | ```
38 |
39 | Easy!
40 |
41 | ### Plugin Options
42 |
43 | Behind the scenes, Laravel Mix of course defers to webpack's `sass-loader` to load and compile your Sass files.
44 | From time to time, you may need to override the default options that we pass to it. Use the third argument to `mix.sass()` in these scenarios.
45 |
46 | ```js
47 | mix.sass('src/app.scss', 'dist', {
48 | sassOptions: {
49 | outputStyle: 'nested'
50 | }
51 | });
52 | ```
53 |
54 | For a full list of supported options, please [refer to the webpack documentation](https://webpack.js.org/loaders/sass-loader/#options) for `sass-loader`.
55 |
56 | ### Multiple Outputs
57 |
58 | Should you need to compile more than one root file, you may call `mix.sass()` as many as times as necessary. For each call, webpack will output a new file with the relevant contents.
59 |
60 | ```js
61 | mix.sass('src/app.scss', 'dist/') // creates 'dist/app.css'
62 | .sass('src/forum.scss', 'dist/'); // creates 'dist/forum.css'
63 | ```
64 |
--------------------------------------------------------------------------------
/stylus.md:
--------------------------------------------------------------------------------
1 | # Stylus Preprocessing
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Plugin Options](#plugin-options)
5 | - [Multiple Outputs](#multiple-outputs)
6 |
7 | ### Basic Usage
8 |
9 | Here's a quick example to get you started. Imagine that you have the following Stylus file that needs to be compiled to vanilla CSS.
10 |
11 | ```stylus
12 | // src/app.styl
13 |
14 | $primary = grey
15 |
16 | .app
17 | background: $primary
18 | ```
19 |
20 | No problem. Let's add Stylus compilation to our `webpack.mix.js` file.
21 |
22 | ```js
23 | // webpack.mix.js
24 | let mix = require('laravel-mix');
25 |
26 | mix.stylus('src/app.styl', 'dist');
27 | ```
28 |
29 | Compile this down as usual \(`npx mix`\), and you'll find a `/dist/app.css` file that contains:
30 |
31 | ```css
32 | .app {
33 | background: grey;
34 | }
35 | ```
36 |
37 | Easy!
38 |
39 | ### Plugin Options
40 |
41 | Behind the scenes, Laravel Mix of course defers to webpack's `stylus-loader` to load and compile your Stylus files.
42 | From time to time, you may need to override the default options that we pass to it. Use the third argument to `mix.stylus()` in these scenarios.
43 |
44 | For a full list of supported options, please [refer to the webpack documentation](https://github.com/webpack-contrib/stylus-loader#options) for `stylus-loader`.
45 |
46 | Foe example, you may wish to install additional Stylus-specific plugins, such as [Rupture](https://github.com/jescalan/rupture). No problem. Simply install the plugin in question through NPM (`npm install rupture`), and then include it in your `mix.stylus()` call, like so:
47 |
48 | ```js
49 | mix.stylus('src/app.styl', 'dist', {
50 | stylusOptions: {
51 | use: [require('rupture')()]
52 | }
53 | });
54 | ```
55 |
56 | Should you wish to take it further and automatically import plugins globally, you may use the `import` option. Here's an example:
57 |
58 | ```js
59 | mix.stylus('resources/assets/stylus/app.styl', 'public/css', {
60 | use: [require('rupture')(), require('nib')(), require('jeet')()],
61 | import: ['~nib/index.styl', '~jeet/jeet.styl']
62 | });
63 | ```
64 |
65 | ### Multiple Outputs
66 |
67 | Should you need to compile more than one root file, you may call `mix.stylus()` as many as times as necessary. For each call, webpack will output a new file with the relevant contents.
68 |
69 | ```js
70 | mix.stylus('src/app.styl', 'dist/') // creates 'dist/app.css'
71 | .stylus('src/forum.styl', 'dist/'); // creates 'dist/forum.css'
72 | ```
73 |
--------------------------------------------------------------------------------
/upgrade.md:
--------------------------------------------------------------------------------
1 | # Upgrade to Mix 6
2 |
3 | - [Review Your Dependencies](#review-your-dependencies)
4 | - [Update Your NPM Scripts](#update-your-npm-scripts)
5 | - [Watch Ignores node_modules](#watch-ignores-node-modules)
6 | - [API for JavaScript Frameworks](#api-for-javascript-frameworks)
7 | - [Vue Configuration](#vue-configuration)
8 | - [Autoprefixer Options](#autoprefixer-options)
9 | - [Unused Library Extraction](#unused-library-extraction)
10 | - [Automatically Ignored node_modules](#automatically-ignore-node-modules)
11 |
12 | ```bash
13 | npm install laravel-mix@latest
14 | ```
15 |
16 | ## Review Your Dependencies
17 |
18 | Laravel Mix 6 ships with support for the latest versions of numerous dependencies, including webpack 5, PostCSS 8, Vue Loader 16, and more.
19 | These are significant releases with their own sets of breaking changes. We've done our best to normalize these changes, but it's still particularly important that you take the time to fully test your build after upgrading to Mix 6.
20 |
21 | Please review your `package.json` dependencies list for any third-party tools or plugins that may not yet be compatible with webpack 5 or PostCSS 8.
22 |
23 | ## Update Your NPM Scripts
24 |
25 | If your build throws an error such as `Unknown argument: --hide-modules`, the `scripts` section of your `package.json` file will need to be updated. The Webpack 5 CLI removed a number of options that your NPM scripts was likely referencing.
26 |
27 | While you're at it, go ahead and switch over to the new Mix CLI.
28 |
29 | ### Before
30 |
31 | ```js
32 | "scripts": {
33 | "development": "cross-env NODE_ENV=development node_modules/webpack/bin/webpack.js --progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js",
34 | "watch": "npm run development -- --watch",
35 | "watch-poll": "npm run watch -- --watch-poll",
36 | "hot": "cross-env NODE_ENV=development node_modules/webpack-dev-server/bin/webpack-dev-server.js --inline --hot --disable-host-check --config=node_modules/laravel-mix/setup/webpack.config.js",
37 | "production": "cross-env NODE_ENV=production node_modules/webpack/bin/webpack.js --no-progress --hide-modules --config=node_modules/laravel-mix/setup/webpack.config.js"
38 | }
39 | ```
40 |
41 | ### After
42 |
43 | ```js
44 | "scripts": {
45 | "development": "mix",
46 | "watch": "mix watch",
47 | "watch-poll": "mix watch -- --watch-options-poll=1000",
48 | "hot": "mix watch --hot",
49 | "production": "mix --production"
50 | }
51 | ```
52 |
53 | ## Watch Ignores `node_modules`
54 |
55 | Mix will now ignore the `node_modules/` directory when watching files for changes. This allows for a nice performance boost. However, if your project depends on that functionality, you may override the generated webpack configuration, like so:
56 |
57 | ```
58 | mix.override((config) => {
59 | delete config.watchOptions;
60 | });
61 | ```
62 |
63 | ## API for JavaScript Frameworks
64 |
65 | Laravel Mix was originally built to be quite opinionated. One of these opinions was that Vue support should be provided out
66 | of the box. Any call to `mix.js()` would instantly come with the benefit of Vue single-file components.
67 |
68 | Though we're not removing Vue support by any stretch, we _have_ extracted Vue to its own "featured flag": `mix.vue()`.
69 |
70 | ### Before
71 |
72 | ```js
73 | mix.js('resources/js/app.js', 'public/js');
74 | ```
75 |
76 | ### After
77 |
78 | ```js
79 | mix.js('resources/js/app.js', 'public/js').vue();
80 | ```
81 |
82 | Think of this as your way of saying, "_I want to compile my JavaScript **and also** turn on Vue support._" Mix will automatically detect whether you have Vue 2 or 3 installed, based on your dependencies list.
83 | However, if you'd rather be explicit...
84 |
85 | ```js
86 | mix.js('resources/js/app.js', 'public/js').vue({ version: 2 });
87 | ```
88 |
89 | The same is true for React.
90 |
91 | ### Before
92 |
93 | ```js
94 | mix.react('resources/js/app.js', 'public/js');
95 | ```
96 |
97 | ### After
98 |
99 | ```js
100 | mix.js('resources/js/app.js', 'public/js').react();
101 | ```
102 |
103 | ## Vue Configuration
104 |
105 | In line with the previous change, any Vue-specific configuration that was stored on the global `Config` object should now
106 | be passed directly to the `mix.vue()` command, like so:
107 |
108 | ### Before
109 |
110 | ```js
111 | mix.js('resources/js/app.js', 'public/js').options({
112 | extractVueStyles: true,
113 | globalVueStyles: false
114 | });
115 | ```
116 |
117 | ### After
118 |
119 | ```js
120 | mix.js('resources/js/app.js', 'public/js').vue({
121 | extractStyles: true,
122 | globalStyles: false
123 | });
124 | ```
125 |
126 | > {note} Please note the slight property name change: `extractVueStyles` => `extractStyles`.
127 |
128 | ## Autoprefixer Options
129 |
130 | If your `webpack.mix.js` applied custom Autoprefixer options, we've adjusted and simplified the configuration slightly.
131 |
132 | ### Before
133 |
134 | ```js
135 | mix.options({
136 | autoprefixer: {
137 | enabled: true,
138 | options: { remove: false }
139 | }
140 | });
141 | ```
142 |
143 | ### After
144 |
145 | ```js
146 | mix.options({
147 | autoprefixer: { remove: false }
148 | });
149 | ```
150 |
151 | You can disable autoprefixer entirely, by setting it to `false`.
152 |
153 | ```js
154 | mix.options({
155 | autoprefixer: false
156 | });
157 | ```
158 |
159 | ## Unused Library Extraction
160 |
161 | When given `mix.extract(["library-1", "library-2"])`, Mix would previously extract the referenced libraries to a file **regardless** of whether they're used in the main JS bundle.
162 | Mix 6, however, extracts **only** the libraries that are used by your JS bundle. This means that these libraries are now also eligible for tree-shaking.
163 |
164 | With this change, libraries should no longer be duplicated in multiple files. For example, if you used `vue` in your JS bundle and called `mix.extract(["vue"])` it was possible in some scenarios for Vue to be included in both the vendor file **and** your app JS file. This should no longer happen.
165 |
166 | Should you need to preserve the behavior of all listed libraries being included, you'll need to create a file that imports the necessary libraries. It may also be necessary for you to disable tree-shaking optimizations.
167 |
168 | ### Before
169 |
170 | ```js
171 | // webpack.mix.js
172 | mix.extract(['library-1', 'library-2']);
173 | ```
174 |
175 | ### After
176 |
177 | ```js
178 | // src/libraries.js
179 | import 'library-1';
180 | import 'library-2';
181 |
182 | // webpack.mix.js
183 | mix.js('src/libraries.js');
184 |
185 | mix.extract(['library-1', 'library-2']);
186 |
187 | mix.webpackConfig({
188 | optimization: {
189 | providedExports: false,
190 | sideEffects: false,
191 | usedExports: false
192 | }
193 | });
194 | ```
195 |
196 | ## Automatically Ignore node_modules
197 |
198 | Mix will now ignore the `node_modules` directory when watching for changes. If your current `webpack.mix.js` file does this explicitly, it can now safely be removed.
199 |
200 | ### Before
201 |
202 | ```js
203 | mix.js('src/app.js', 'dist');
204 |
205 | mix.webpackConfig({
206 | watchOptions: { ignored: /node_modules/ }
207 | });
208 | ```
209 |
210 | ### After
211 |
212 | ```js
213 | mix.js('src/app.js', 'dist');
214 | ```
215 |
--------------------------------------------------------------------------------
/url-rewriting.md:
--------------------------------------------------------------------------------
1 | # CSS URL Rewriting
2 |
3 | - [An Example](#an-example)
4 |
5 | One key concept to understand is that Mix and webpack will rewrite any `url()`s within your stylesheets. While this might initially sound strange, it's incredibly powerful.
6 |
7 | ### An Example
8 |
9 | Imagine that you want to compile a bit of Sass that includes a url to an image.
10 |
11 | ```scss
12 | .example {
13 | background: url('../images/thing.png');
14 | }
15 | ```
16 |
17 | Notice how that the URL is a relative path? By default, Laravel Mix and webpack will locate `thing.png`, copy it to your `dist/images` folder, and then rewrite the `url()` to point to the new output location within your generated stylesheet. As such, your compiled CSS will ultimately be:
18 |
19 | ```css
20 | .example {
21 | background: url(/images/thing.png?d41d8cd98f00b204e9800998ecf8427e);
22 | }
23 | ```
24 |
25 | > {tip} Absolute paths for `url()`s will always be excluded from url-rewriting. For instance, `url('/images/thing.png')` or `url('http://example.com/images/thing.png')` won't be touched.
26 |
27 | This, again, is a very cool feature of webpack's. However, it does have a tendency to confuse those who don't understand how webpack and its css-loader plugin works.
28 | It's possible that your folder structure is already just how you want it, and you'd prefer that Mix not modify those `url()`s. If that's the case, we do offer an override:
29 |
30 | ```js
31 | mix.sass('src/app.scss', 'dist').options({
32 | processCssUrls: false
33 | });
34 | ```
35 |
36 | With this addition to your `webpack.mix.js` file, Mix will no longer match `url()`s or copy assets to your public directory. Instead, your compiled CSS will remain exactly as you typed it:
37 |
38 | ```css
39 | .example {
40 | background: url('../images/thing.png');
41 | }
42 | ```
43 |
44 | > As a bonus, when you disable url processing, your Webpack Sass compilation will be much faster.
45 |
46 | ### Per-file rewrite settings
47 |
48 | Url rewriting can be controlled on a per-file basis by specifying the `processUrls` option. This option will take precedence over what has been specified via the `processCssUrls` mix option.
49 |
50 | ```js
51 | mix.options({
52 | // Don't perform any css url rewriting by default
53 | processCssUrls: false,
54 | })
55 |
56 | mix.sass('src/app.scss', 'dist', {
57 | // Rewrite CSS urls for app.scss
58 | processUrls: true,
59 | });
60 |
61 | mix.sass('src/admin.scss', 'dist');
62 | mix.sass('src/other.scss', 'dist');
63 | ```
64 |
--------------------------------------------------------------------------------
/versioning.md:
--------------------------------------------------------------------------------
1 | # Versioning
2 |
3 | - [Basic Usage](#basic-usage)
4 | - [Importing Versioned Files](#importing-versioned-files)
5 |
6 | ### Basic Usage
7 |
8 | To assist with long-term caching, Laravel Mix provides the `mix.version()` method to enable file hashing, such as `app.js?id=8e5c48eadbfdd5458ec6`. This is useful for cache-busting purposes.
9 |
10 | ```js
11 | // 1. Version all compiled assets.
12 | mix.version();
13 |
14 | // 2. Version compiled assets AND public/js/file.js
15 | mix.version(['public/js/file.js']);
16 | ```
17 |
18 | Imagine that your server automatically caches scripts for one year to improve performance. That's great, but each time you make a change to your application code, you need some way to instruct the server to bust the cache. This is typically done through the use of query strings or file hashing.
19 |
20 | With Mix versioning enabled, a unique querystring id will be appended to your assets every time your code is compiled. Consider the following `webpack.mix.js` file.
21 |
22 | ```js
23 | let mix = require('laravel-mix');
24 |
25 | mix.js('src/app.js', 'dist/js')
26 | .sass('src/app.sass', 'dist/css')
27 | .version();
28 | ```
29 |
30 | Upon compilation, you'll see `/css/app.css?id=5ee7141a759a5fb7377a` and `/js/app.js?id=0441ad4f65d54589aea5` in your `mix-manifest.json` file. Of course, your particular hash will be different. Each time you adjust your JavaScript, the compiled files will receive a newly hashed name, which will effectively bust the cache once pushed to production.
31 |
32 | If you'd like to test it, run `npx mix watch` and then change a bit of your JavaScript. Return to `mix-manifest.json` and you'll notice that, for each change, the unique hash changes.
33 |
34 | ### Importing Versioned Files
35 |
36 | This all begs the question: in our HTML file, how can we make the name of the script and stylesheet dynamic, based on their respective values within the `mix-manifest.json` file? Yes, that can be tricky.
37 |
38 | The answer will be dependent upon the type of application you're building. For SPAs, you may dynamically read Laravel Mix's generated `mix-manifest.json` file, extract the asset file names, and then generate your HTML.
39 |
40 | #### Laravel Users
41 |
42 | For Laravel projects, a solution is provided out of the box. Simply call its global `mix()` function, and you're done! Here's a quick example:
43 |
44 | ```html
45 |
46 |
47 |