Webpack¶
Current Webpack version: 4.5.0
This role provides a pretty simple setup to handle assets (javascripts, stylesheets, images, fonts and SVG icons) through Webpack in your project.
It creates a webpack.config.js that is preconfigured to handle:
- Sass files to create stylesheets. Stylesheets are processed through Autoprefixer for browser compatibility and CSSNano for optimisations.
- JavaScript files through Babel with babel-preset-env to use next generation JavaScript today
- SVG icons through svg-sprite-loader and make a single sprite file out of it
- Images (svg, png, jp(e)g, gif, webp)
- Fonts (woff, woff2, eot, ttf, otf)
Installation¶
Once enabled, this role will create a webpack.config.js
, a babel.config.js
and a package.json
that includes all the required dependencies by default.
Existing files (webpack.config.js, babel.config.js and package.json) will not be overridden. If those files already exist, the installation will be incomplete and might not work as expected.
Parameters¶
webpack_directory: where should the webpack.config.js be created, defaults to
{{ root_directory }}/
webpack_create_config: Create the webpack.config.js & babel.config.js, defaults to
true
webpack_browserslist: Define Browserslist in
package.json
, defaults to:- "> 0.5%" - "not op_mini all" - "not dead"
Post-install¶
The default configuration expects a couple of things:
- The main JavaScript file to live at
assets/scripts/common.js
(not created by the role) - All the assets to live in
assets/…
or innode_modules
- The SVG icons to be included in the sprite to live in
assets/icons/
Other defaults:
- Built files are bundled into the
dist/
folder - Generated icons sprite is named
icons.svg
You can change all these default values by editing the webpack.config.js
file. If you need help, you should check out the Webpack config documentation.
Default tasks¶
Development¶
npm start
Starts webpack-dev-server
at example.lo:3000, compile on-the-fly and reload the browser automatically. All requests not handled by webpack will be proxified to example.lo.
Replace example.lo by the “hostname” you set in the “parameters.yml”.
Notice that webpack-dev-server does not write the files to the disk. To debug which files are being served, go to example.lo:3000/webpack-dev-server.
Production¶
npm run build
Will bundle all the assets, optimized for production, in the dist
folder by default.
Loading assets¶
The default public path for bundled assets is /
.
To load the main JavaScript file, use:
<script type="text/javascript" src="common.js"></script>
In development, CSS is automatically injected in a <style>
tag by the JavaScript file that imported it. In production, you need to include the extracted file. For example, all the CSS required by the common
bundle, would be extracted as common.css
and should be loaded like this:
<link rel="stylesheet" type="text/css" href="common.css">
If you need help to import files such as CSS, images or fonts, take a look to the Webpack asset management guide.