diff --git a/doc/article/en-US/setup-webpack.md b/doc/article/en-US/setup-webpack.md index 3c41534f..8e0611a5 100644 --- a/doc/article/en-US/setup-webpack.md +++ b/doc/article/en-US/setup-webpack.md @@ -85,3 +85,583 @@ Integration tests are performed with [Protractor](http://angular.github.io/protr ```shell npm run e2e:start ``` + +## [Using Normal Webpack Configuration](aurelia-doc://section/7/version/1.0.0) + +#### 1. Basic Usage + +1. Dependencies + * After downloading skeleton-esnext-webpack from Aurelia github, + we replace any reference to `@easy-webpack` with the normal webpack modules.
+ In `package.json`, remove all modules that start with `@easy-webpack` in `devDependencies`:

+ + ```json + "@easy-webpack/config-aurelia": "^2.0.1", + "@easy-webpack/config-babel": "^2.0.2", + "@easy-webpack/config-common-chunks-simple": "^2.0.1", + "@easy-webpack/config-copy-files": "^1.0.0", + "@easy-webpack/config-css": "^2.3.2", + "@easy-webpack/config-env-development": "^2.1.1", + "@easy-webpack/config-env-production": "^2.1.0", + "@easy-webpack/config-external-source-maps": "^2.0.1", + "@easy-webpack/config-fonts-and-images": "^1.2.1", + "@easy-webpack/config-generate-index-html": "^2.0.1", + "@easy-webpack/config-global-bluebird": "^1.2.0", + "@easy-webpack/config-global-jquery": "^1.2.0", + "@easy-webpack/config-global-regenerator": "^1.2.0", + "@easy-webpack/config-html": "^2.0.2", + "@easy-webpack/config-json": "^2.0.2", + "@easy-webpack/config-test-coverage-istanbul": "^2.0.2", + "@easy-webpack/config-uglify": "^2.1.0", + "@easy-webpack/core": "^1.3.2", + ``` + + with the following: + + ```json + "aurelia-webpack-plugin": "^1.1.0", + "copy-webpack-plugin": "^3.0.1", + "html-webpack-plugin": "^2.22.0", + "babel-core": "^6.17.0", + "babel-loader": "^6.2.5", + "babel-polyfill": "^6.16.0", + "css-loader": "^0.25.0", + "file-loader": "^0.9.0", + "sourcemap-istanbul-instrumenter-loader": "^0.2.0", + "style-loader": "^0.13.1", + "url-loader": "^0.5.7", + "html-loader": "^0.4.4" + ``` + + Also, change bundler (webpack) to the latest version by replacing: + ```json + "webpack": "^2.1.0-beta.22" + ``` + with + + ```json + "webpack": "^2.1.0-beta.25" + ``` + +2. Basic Configuration + + ```js + const path = require('path'); + const webpack = require('webpack'); + const HtmlWebpackPlugin = require('html-webpack-plugin'); + const AureliaWebpackPlugin = require('aurelia-webpack-plugin'); + const project = require('./package.json'); + + module.exports = { + entry: { + 'app': [], // <-- this array will be filled by the aurelia-webpack-plugin + 'aurelia': Object.keys(project.dependencies).filter(dep => dep.startsWith('aurelia-')) + }, + output: { + path: path.resolve('dist'), + filename: '[name].bundle.js' + }, + module: { + rules: [ + { + test: /\.js$/, + exclude: /node_modules/, + loader: 'babel-loader', + query: { + presets: ['es2015', 'stage-1'], + plugins: ['transform-decorators-legacy'] + } + }, + { + test: /\.html$/, + exclude: /index\.html$/, // index.html will be taken care by HtmlWebpackPlugin + use: 'html-loader' + }, + { + test: /\.css$/, + use: ['style-loader', 'css-loader'] + }, + { + test: /\.(png|jpe?g|gif|svg|eot|woff|woff2|ttf)$/, + use: 'url-loader' + } + ] + }, + plugins: [ + new webpack.ProvidePlugin({ + regeneratorRuntime: 'regenerator-runtime', // to support await/async syntax + Promise: 'bluebird', // because Edge browser has slow native Promise object + $: 'jquery', // because 'bootstrap' by Twitter depends on this + jQuery: 'jquery', // just an alias + }), + new HtmlWebpackPlugin({ + template: 'index.html' + }), + new AureliaWebpackPlugin({ + root: path.resolve(), + src: path.resolve('src'), + baseUrl: '/' + }), + new webpack.optimize.CommonsChunkPlugin({ + name: ['aurelia'] + }) + ] + }; + ``` + +3. Change our `index.html` to + + ```html + + + + Aurelia Navigation Skeleton + + + + + + + +
+
Aurelia Navigation Skeleton
+ +
+ + + + + ``` + +4. Install dependencies + + ```shell + npm install + ``` + +5. Adjust development tasks
+ Modify the dev task so it doesn't throw an error, + by replacing old dev task in `package.json` + with the slightly different version (without `--progress`)
+ Replace: + + ```json + "server:dev": "cross-env NODE_ENV=development node ./node_modules/webpack-dev-server/bin/webpack-dev-server --inline --progress --profile --watch", + ``` + + With: + + ```json + "server:dev": "cross-env NODE_ENV=development node ./node_modules/webpack-dev-server/bin/webpack-dev-server --inline --profile --watch", + ``` + +6. Start development + + ```shell + npm start + ``` + +#### 2. Advanced Usage + +1. **Template optimization** + * Additional dependencies for handling template, + as Aurelia templates need to be optimized to reduce bundle size: + + ```json + "raw-loader": "^0.5.1", + "html-minifier": "^3.1.0", + "html-minifier-loader": "^1.3.3", + ``` + + * **IMPORTANT**: Start from `webpack@2.1.0-beta.23` (current version: `@beta.25`), custom properties are no longer allowed + on base config object, So we will be using `webpack.LoaderOptionsPlugin` to provide + some config options for `html-minifier-loader`. + + * Modify our config in `webpack.config.js` by replacing: + + ```js + { + test: /\.html$/, + exclude: /index\.html$/, // index.html will be taken care by HtmlWebpackPlugin + use: 'html-loader' + } + ``` + + With: + + ```js + { + test: /\.html$/, + exclude: /index\.html$/, // index.html will be taken care by HtmlWebpackPlugin + use: [ + 'raw-loader', + 'html-minifier-loader' + ] + } + ``` + + Also add to `plugins` config: + + ```js + new webpack.LoaderOptionsPlugin({ + options: { + context: __dirname, + 'html-minifier-loader': { + removeComments: true, // remove all comments + collapseWhitespace: true, // collapse white space between block elements (div, header, footer, p etc...) + collapseInlineTagWhitespace: true, // collapse white space between inline elements (button, span, i, b, a etc...) + collapseBooleanAttributes: true, // => + removeAttributeQuotes: true, // => + minifyCSS: true, // => + minifyJS: true, // same with CSS but for javascript + removeScriptTypeAttributes: true, //