|
| 1 | +--- |
| 2 | +title: Get Started with Webpack |
| 3 | +contributors: |
| 4 | + - bebraw |
| 5 | +sort: 3 |
| 6 | +--- |
| 7 | + |
| 8 | +## Getting Started |
| 9 | + |
| 10 | +webpack is a tool to build JavaScript modules in your application. To start using `webpack` from its [cli](/api/cli) or [api](/api/node), follow the [Installation instructions](/get-started/install-webpack). |
| 11 | +webpack simplifies your workflow by quickly constructing a dependency graph of your application and bundling them in the right order. webpack can be configured to customise optimisations to your code, to split vendor/css/js code for production, run a development server that hot-reloads your code without page refresh and many such cool features. Learn more about [why you should use webpack](/get-started/why-webpack). |
| 12 | + |
| 13 | +## Creating a bundle |
| 14 | + |
| 15 | +Create a demo directory to try out webpack. [Install webpack](/get-started/install-webpack). |
| 16 | + |
| 17 | +```bash |
| 18 | +mkdir webpack-demo && cd webpack-demo |
| 19 | +npm init -y |
| 20 | +npm install --save-dev webpack |
| 21 | +webpack --help # Shows a list of valid cli commands |
| 22 | +npm install --save lodash |
| 23 | +``` |
| 24 | + |
| 25 | +Now create an `index.js` file. |
| 26 | + |
| 27 | +__app/index.js__ |
| 28 | + |
| 29 | +```javascript |
| 30 | +function component () { |
| 31 | + var element = document.createElement('div'); |
| 32 | + |
| 33 | + /* lodash is required for the next line to work */ |
| 34 | + element.innerHTML = _.map(['Hello','webpack'], function(item){ |
| 35 | + return item + ' '; |
| 36 | + }); |
| 37 | + |
| 38 | + return element; |
| 39 | +} |
| 40 | + |
| 41 | +document.body.appendChild(component()); |
| 42 | +``` |
| 43 | + |
| 44 | +To run this piece of code, one usually has the below html |
| 45 | + |
| 46 | +__index.html__ |
| 47 | + |
| 48 | +```html |
| 49 | +<html> |
| 50 | + <head> |
| 51 | + <title>Webpack demo</title> |
| 52 | + < script src= 'https://unpkg.com/[email protected]' type= 'text/javascript'></ script> |
| 53 | + <script src='index.js' type='text/javascript'></script> |
| 54 | + </head> |
| 55 | + <body> |
| 56 | + </body> |
| 57 | +</html> |
| 58 | +``` |
| 59 | + |
| 60 | +In this example, there are implicit dependencies between the script tags. |
| 61 | + |
| 62 | +`index.js` depends on `lodash` being included in the page before it runs. It is implicit because `index.js` never declared a need for `lodash`; it just assumes that a global variable `_` exists. |
| 63 | + |
| 64 | +There are problems with managing JavaScript projects this way: |
| 65 | + - If a dependency is missing, or is included in the wrong order, the application will not function at all. |
| 66 | + - If a dependency is included but is not used, then there is a lot of unnecessary code that the browser has to download. |
| 67 | + |
| 68 | +To bundle the `lodash` dependency with the `index.js`, we need to import `lodash`. |
| 69 | + |
| 70 | +__app/index.js__ |
| 71 | + |
| 72 | +```diff |
| 73 | ++ import _ from `lodash`; |
| 74 | + |
| 75 | +function component () { |
| 76 | + ... |
| 77 | +``` |
| 78 | + |
| 79 | +Also we will need to change the `index.html` to expect a single bundled js file. |
| 80 | + |
| 81 | +```diff |
| 82 | +<html> |
| 83 | + <head> |
| 84 | + <title>Webpack demo</title> |
| 85 | +- <script src='https://unpkg.com/[email protected]' type='text/javascript'></script> |
| 86 | +- <script src='index.js' type='text/javascript'></script> |
| 87 | ++ <script src='dist/bundle.js' type='text/javascript'></script> |
| 88 | + </head> |
| 89 | + <body> |
| 90 | + <div id='root'></div> |
| 91 | + </body> |
| 92 | +</html> |
| 93 | +``` |
| 94 | + |
| 95 | +Here, `index.js` explicitly requires `lodash` to be present, and binds it as `_` (no global scope pollution). |
| 96 | + |
| 97 | +By stating what dependencies a module needs, webpack can use this information to build a dependency graph. It then uses the graph to generate an optimized bundle where scripts will be executed in the correct order. Also unused dependencies will not be included in the bundle. |
| 98 | + |
| 99 | +Now run `webpack` on this folder with the entry file to be `index.js` and to output a `bundle.js` file which bundles all the code required for the page. |
| 100 | + |
| 101 | +```bash |
| 102 | +webpack app/index.js dist/bundle.js |
| 103 | + |
| 104 | +Hash: a3c861a7d42fc8944524 |
| 105 | +Version: webpack 2.2.0 |
| 106 | +Time: 90ms |
| 107 | + Asset Size Chunks Chunk Names |
| 108 | +index.js 1.56 kB 0 [emitted] main |
| 109 | + [0] ./app/index.js 170 bytes {0} [built] |
| 110 | + |
| 111 | +``` |
| 112 | + |
| 113 | +## Using webpack with a config |
| 114 | + |
| 115 | +For more complex configuration, we can use a configuration file that webpack can reference to bundle your code. |
| 116 | +The above CLI command would be represented in config as follows - |
| 117 | + |
| 118 | +__webpack.config.js__ |
| 119 | +```javascript |
| 120 | +module.exports = { |
| 121 | + entry: './app/index.js' |
| 122 | + output: { |
| 123 | + filename: 'bundle.js', |
| 124 | + path: './dist' |
| 125 | + } |
| 126 | +} |
| 127 | +``` |
| 128 | + |
| 129 | +This file can be run by webpack as |
| 130 | + |
| 131 | +```bash |
| 132 | +webpack --config webpack.config.js |
| 133 | + |
| 134 | +Hash: a3c861a7d42fc8944524 |
| 135 | +Version: webpack 2.2.0 |
| 136 | +Time: 90ms |
| 137 | + Asset Size Chunks Chunk Names |
| 138 | +index.js 1.56 kB 0 [emitted] main |
| 139 | + [0] ./app/index.js 170 bytes {0} [built] |
| 140 | + |
| 141 | +``` |
| 142 | +T> If a `webpack.config.js` is present, `webpack` command picks it up by default. |
| 143 | + |
| 144 | +The config file allows for all the flexibility in using webpack. We can add loader rules, plugins, resolve options and many other enhancements to our bundles using this configuration file. |
| 145 | + |
| 146 | +## Using webpack with npm |
| 147 | + |
| 148 | +Given it's not particularly fun to run webpack from the CLI this way, we can set up a little shortcut. Adjust *package.json* like this: |
| 149 | + |
| 150 | +```json |
| 151 | +{ |
| 152 | + ... |
| 153 | + "scripts": { |
| 154 | + "build": "webpack --" |
| 155 | + }, |
| 156 | + ... |
| 157 | +} |
| 158 | +``` |
| 159 | + |
| 160 | +You can now achieve the same as above by using `npm run build` command. npm picks up the scripts through it and patches the environment temporarily so that it contains the bin commands. You will see this convention a lot of projects out there. |
| 161 | + |
| 162 | +T> I use `webpack --` so that we can pass custom parameters to webpack through npm. |
| 163 | + |
| 164 | +## Conclusion |
| 165 | + |
| 166 | +Now that you have a basic build together, you should dig into the [basic concepts](/concepts) and [configuration](/configuration) of webpack to understand its design better. Check out also the [how to section](/how-to) in order to see how to resolve common problems. The [API](/api) section digs into lower level. |
| 167 | + |
0 commit comments