|
| 1 | +# modules-webpack |
| 2 | + |
| 3 | +## Goal |
| 4 | + |
| 5 | +As developer you want to reuse existing code. |
| 6 | +As with node.js and web all file are already in the same language, but it is extra work to use your code with the node.js module system and the browser. |
| 7 | +The goal of `webpack` is to bundle CommonJs modules into javascript files which can be loaded by `<script>`-tags. |
| 8 | +Concating all required file has a disadvantage: many code to download (and execute) on page load. |
| 9 | +Therefor `webpack` uses the `require.ensure` function to split your code automatically into multiple bundles which are loaded on demand. |
| 10 | +This happens mostly transparent to the developer with a single function call. Dependencies are resolved for you. |
| 11 | +The result is a smaller inital code download which results in faster page load. |
| 12 | + |
| 13 | +**TL;DR** |
| 14 | + |
| 15 | +* bundle CommonJs modules |
| 16 | +* create multiple files which are loaded on demand |
| 17 | +* dependencies managed for you |
| 18 | +* faster page load in big webapps |
| 19 | + |
| 20 | +## Example |
| 21 | + |
| 22 | +``` javascript |
| 23 | +// a.js |
| 24 | +var b = require("./b"); |
| 25 | +b.stuff("It works"); |
| 26 | + |
| 27 | +// b.js |
| 28 | +exports.stuff = function(text) { |
| 29 | + console.log(text); |
| 30 | +} |
| 31 | +``` |
| 32 | + |
| 33 | +are compiled to |
| 34 | + |
| 35 | +``` javascript |
| 36 | +(/* small webpack header */) |
| 37 | +({ |
| 38 | +0: function(module, exports, require) { |
| 39 | + |
| 40 | + var b = require(1); |
| 41 | + b.stuff("It works"); |
| 42 | + |
| 43 | +}, |
| 44 | +1: function(module, exports, require) { |
| 45 | + |
| 46 | + exports.stuff = function(text) { |
| 47 | + console.log(text); |
| 48 | + } |
| 49 | + |
| 50 | +} |
| 51 | +}) |
| 52 | +``` |
| 53 | + |
| 54 | +## Browser replacements |
| 55 | + |
| 56 | +Somethings it happens that browsers require other code than node.js do. |
| 57 | +`webpack` allow module developers to specify replacements which are used in the compile process of `webpack`. |
| 58 | + |
| 59 | +Modules in `web_modules` replace modules in `node_modules`. |
| 60 | +`filename.web.js` replaces `filename.js` when required without file extention. |
| 61 | + |
| 62 | +TODO specify replacements in options |
| 63 | + |
| 64 | +## Limitations |
| 65 | + |
| 66 | +### `require`-function |
| 67 | + |
| 68 | +As dependencies are resolved before running: |
| 69 | +* `require` should not be overwritten |
| 70 | +* `require` should not be called indirect as `var r = require; r("./a");` |
| 71 | +* arguments of `require` should be literals. `"./abc" + "/def"` is allowed to support long lines. |
| 72 | +* `require.ensure` has the same limitations as `require` |
| 73 | +* the function passed to `require.ensure` should be inlined in the call. |
| 74 | + |
| 75 | +TODO allow variables passing to `require` like `require("./templates/" + mytemplate)` |
| 76 | +(this will cause all modules matching this pattern to be included in addition to a mapping table) |
| 77 | + |
| 78 | +### node.js specific modules |
| 79 | + |
| 80 | +As node.js specific modules like `fs` will not work in browser they are not included and cause an error. |
| 81 | +You should replace them be own modules if your use them. |
| 82 | + |
| 83 | +``` |
| 84 | +web_modules |
| 85 | + fs |
| 86 | + path |
| 87 | + ... |
| 88 | +``` |
| 89 | + |
| 90 | +## Code Splitting |
| 91 | + |
| 92 | +### Example |
| 93 | + |
| 94 | +``` javascript |
| 95 | +var a = require("a"); |
| 96 | +var b = require("b"); |
| 97 | +require.ensure(["c"], function(require) { |
| 98 | + require("b").xyz(); |
| 99 | + var d = require("d"); |
| 100 | +}); |
| 101 | +``` |
| 102 | + |
| 103 | +``` |
| 104 | +File 1: web.js |
| 105 | +- code of module a and dependencies |
| 106 | +- code of module b and dependencies |
| 107 | +
|
| 108 | +File 2: 1.web.js |
| 109 | +- code of module c and dependencies (but code is not used) |
| 110 | +- code of module d and dependencies |
| 111 | +``` |
| 112 | + |
| 113 | +See [details](modules-webpack/tree/master/example) for exact output. |
| 114 | + |
| 115 | +## Usage |
| 116 | + |
| 117 | +### Shell |
| 118 | + |
| 119 | +`webpack` offers a command line interface: |
| 120 | + |
| 121 | +after `npm install webpack -g` you can use the `webpack` command |
| 122 | + |
| 123 | +if invoked without arguments it prints a usage: |
| 124 | + |
| 125 | +``` |
| 126 | +Usage: webpack <options> <input> <output> |
| 127 | +
|
| 128 | +Options: |
| 129 | + --single Disable Code Splitting [boolean] [default: false] |
| 130 | + --min Minimize it with uglifyjs [boolean] [default: false] |
| 131 | + --filenames Output Filenames Into File [boolean] [default: false] |
| 132 | + --options Options JSON File [string] |
| 133 | + --script-src-prefix Path Prefix For JavaScript Loading [string] |
| 134 | + --libary Stores the exports into this variable [string] |
| 135 | +``` |
| 136 | + |
| 137 | +### Programmatically Usage |
| 138 | + |
| 139 | +`webpack(context, moduleName, [options], callback)` |
| 140 | +`webpack(absoluteModulePath, [options], callback)` |
| 141 | + |
| 142 | +#### `options` |
| 143 | + |
| 144 | +you can save this options object in a JSON file and use it with the shell command. |
| 145 | + |
| 146 | +`outputJsonpFunction` |
| 147 | +JSONP function used to load chunks |
| 148 | + |
| 149 | +`scriptSrcPrefix` |
| 150 | +Path from where chunks are loaded |
| 151 | + |
| 152 | +`outputDirectory` |
| 153 | +write files to this directory (absolute path) |
| 154 | + |
| 155 | +`output` |
| 156 | +write first chunk to this file |
| 157 | + |
| 158 | +`outputPostfix` |
| 159 | +write chunks to files named chunkId plus outputPostfix |
| 160 | + |
| 161 | +`libary` |
| 162 | +exports of input file are stored in this variable |
| 163 | + |
| 164 | +`minimize` |
| 165 | +minimize outputs with uglify-js |
| 166 | + |
| 167 | +`includeFilenames` |
| 168 | +add absolute filenames of input files as comments |
| 169 | + |
| 170 | +#### `callback` |
| 171 | +`function(err, source / stats)` |
| 172 | +`source` if `options.output` is not set |
| 173 | +else `stats` as json see [example](/modules-webpack/tree/master/example) |
| 174 | + |
| 175 | +## medikoo/modules-webmake |
| 176 | + |
| 177 | +`webpack` as originally intended as fork for `webmake` for @medikoo so it shared several ideas with it. |
| 178 | +So big credit goes to medikoo. |
| 179 | + |
| 180 | +However `webpack` has big differences: |
| 181 | + |
| 182 | +`webpack` replaces module names and paths with numbers. `webmake` don't do that and do resolves requires on client-side. |
| 183 | +This design of `webmake` wes intended to support variables as arguments to require calls. |
| 184 | +`webpack` resolves requires in compile time and have no resolve code on client side. This results in smaller bundles. |
| 185 | +Variables as argments will be handled different and with more limitations. |
| 186 | + |
| 187 | +Another limitation in `webmake` which are based on the previous one is that modules must be in the current package scope. |
| 188 | +In `webpack` this is not a restriction. |
| 189 | + |
| 190 | +The design of `webmake` causes all modules with the same name to overlap. This can be problematic if different submodules rely on specific versions of the same module. The behaivior also differs from the behaivior of node.js, because node.js installs a module for each instance in submodules and `webmake` cause them the merge into a single module which is only installed once. In `webpack` this is not the case. Different versions do not overlap and modules are installed multiple times. But in `webpack` this can (currently) cause duplicate code if a module is used in multiple modules. I want to face this issue (TODO). |
| 191 | + |
| 192 | +`webmake` do (currently) not support Code Splitting. |
| 193 | + |
| 194 | +## Tests |
| 195 | + |
| 196 | +You can run the unit tests which `node_modules/.bin/vows`. |
| 197 | + |
| 198 | +You can run the browser tests: |
| 199 | + |
| 200 | +``` |
| 201 | +cd test/browsertests |
| 202 | +node build |
| 203 | +``` |
| 204 | + |
| 205 | +and open `test.html` in browser. There must be several OKs in the file and no FAIL. |
| 206 | + |
| 207 | +TODO more tests |
| 208 | + |
| 209 | +## Contribution |
| 210 | + |
| 211 | +You are welcome to contribute by writing issues or pull requests. |
| 212 | + |
| 213 | +You are also welcome to correct any spelling mistakes or any language issues, because my english is not so good... |
| 214 | + |
| 215 | +## License |
| 216 | + |
| 217 | +MIT |
5 commit comments
gbmeow commentedon Apr 30, 2018
awesome 👍
revskill10 commentedon Dec 12, 2018
ok
ravencrown commentedon Apr 17, 2019
This is the first commit?
ytICE commentedon Jan 24, 2021
时光荏苒
saideepesh000 commentedon Jul 20, 2021
And the rest, as they say, is history 🔥 🔥