Skip to content

Commit f717032

Browse files
yyx990803yyx990803
committed
update dist files readme
1 parent 1b6a7d4 commit f717032

File tree

1 file changed

+98
-37
lines changed

1 file changed

+98
-37
lines changed

‎dist/README.md

Lines changed: 98 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,124 @@
11
## Explanation of Build Files
22

3-
> A rule of thumb: files that end in `common.js` are meant for built tools, files that do not end in `common.js` are meant for direct browser usage.
3+
| | UMD | CommonJS | ES Module |
4+
| --- | --- | --- | --- |
5+
| **Full** | vue.js | vue.common.js | vue.esm.js |
6+
| **Runtime-only** | vue.runtime.js | vue.runtime.common.js | vue.runtime.esm.js |
7+
| **Full (production)** | vue.min.js | | |
8+
| **Runtime-only (production)** | vue.runtime.min.js | | |
49

5-
- ### vue.js
10+
### Terms
611

7-
The full (compiler-included) browser build. This is the build you can just include with a script tag:
12+
- **Full**: builds that contains both the compiler and the runtime.
813

9-
```
10-
<script src="https://unpkg.com/vue/dist/vue.js"></script>
11-
```
14+
- **Compiler**: code that is responsible for compiling template strings into JavaScript render functions.
1215

13-
Note that this build is hard-coded to development mode.
16+
- **Runtime**: code that is responsible for creating Vue instances, rendering and patching virtual DOM, etc. Basically everything minus the compiler.
1417

15-
- ### vue.min.js
18+
- **[UMD](https://github.com/umdjs/umd)**: UMD builds can be used directly in the browser via a `<script>` tag. The default file from Unpkg CDN at [https://unpkg.com/vue](https://unpkg.com/vue) is the Runtime + Compiler UMD build (`vue.js`).
1619

17-
Same as `vue.js`, but minified AND is hard-coded to production mode (with runtime checks and warnings stripped).
20+
- **[CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1)**: CommonJS builds are intended for use with older bundlers like [browserify](http://browserify.org/) or [webpack 1](https://webpack.github.io). The default file for these bundlers (`pkg.main`) is the Runtime only CommonJS build (`vue.runtime.common.js`).
1821

19-
- ### vue.common.js
22+
- **[ES Module](http://exploringjs.com/es6/ch_modules.html)**: ES module builds are intended for use with modern bundlers like [webpack 2](https://webpack.js.org) or [rollup](http://rollupjs.org/). The default file for these bundlers (`pkg.module`) is the Runtime only ES Module build (`vue.runtime.esm.js`).
2023

21-
The full (compiler-included) CommonJS build. This is the build intended to be used with a Node-compatible bundler, e.g. Webpack or Browserify.
24+
### Runtime + Compiler vs. Runtime-only
2225

23-
The difference between the browser build and the CommonJS build is that the latter preserves the `process.env.NODE_ENV` check for development/production modes (defaults to development mode). This gives you more control over what mode the code should run in:
26+
If you need to compile templates on the fly (e.g. passing a string to the `template` option, or mounting to an element using its in-DOM HTML as the template), you will need the compiler and thus the full build.
2427

25-
- When bundling for the browser, you can turn on production mode by using Webpack's [DefinePlugin](https://webpack.github.io/docs/list-of-plugins.html#defineplugin) to replace `process.env.NODE_ENV` with the `"production"` string literal:
28+
When using `vue-loader` or `vueify`, templates inside `*.vue` files are compiled into JavaScript at build time. You don't really need the compiler in the final bundle, and can therefore use the runtime-only build.
2629

27-
``` js
28-
plugins: [
29-
new webpack.DefinePlugin({
30-
'process.env.NODE_ENV': '"production"'
31-
})
32-
]
33-
```
30+
Since the runtime-only builds are roughly 30% lighter-weight than their full-build counterparts, you should use it whenever you can. If you wish to use the full build instead, you need to configure an alias in your bundler.
3431

35-
This also allows minifiers to completely drop the warnings inside the conditional blocks. For Browserify, you can use [envify](https://github.com/hughsk/envify) to achieve the same.
32+
#### Webpack
3633

37-
- When running Vue in Node.js (during server side rendering), Vue will pick up the actual `process.env.NODE_ENV` if set.
34+
``` js
35+
module.exports = {
36+
// ...
37+
resolve: {
38+
alias: {
39+
'vue$': 'vue/dist/vue.esm.js' // 'vue/dist/vue.common.js' for webpack 1
40+
}
41+
}
42+
}
43+
````
3844

39-
- ### vue.runtime.common.js
45+
#### Rollup
4046

41-
The runtime-only (compiler-excluded) CommonJS build.
47+
``` js
48+
const alias = require('rollup-plugin-alias')
4249
43-
This build does not support the `template` option, because it doesn't include the compiler. It is thus 30% lighter than the full build. However, you can still use templates in Single-File `*.vue` components via `vue-loader` or `vueify`, as these tools will pre-compile the templates into render functions for you.
50+
rollup({
51+
// ...
52+
plugins: [
53+
alias({
54+
'vue': 'vue/dist/vue.esm.js'
55+
})
56+
]
57+
})
58+
```
4459

45-
**This is the default build you get from `import Vue from 'vue'` or `var Vue = require('vue')`**. To use the full CommonJS build instead, configure Webpack via the `resolve.alias` option:
60+
#### Browserify
4661

47-
``` js
48-
resolve: {
49-
alias: {
50-
vue$: 'vue/dist/vue.common.js'
51-
}
62+
Add to your project's `package.json`:
63+
64+
``` js
65+
{
66+
// ...
67+
"browser": {
68+
"vue": "vue/dist/vue.common.js"
5269
}
53-
```
70+
}
71+
```
72+
73+
### Development vs. Production Mode
74+
75+
Development/production modes are hard-coded for the UMD builds: the un-minified files are for development, and the minified files are for production.
76+
77+
CommonJS and ES Module builds are intended for bundlers, therefore we don't provide minified versions for them. You will be responsible for minifying the final bundle yourself.
78+
79+
CommonJS and ES Module builds also preserve raw checks for `process.env.NODE_ENV` to determine the mode they should run in. You should use appropriate bundler configurations to replace these environment variables in order to control which mode Vue will run in. Replacing `process.env.NODE_ENV` with string literals also allows minifiers like UglifyJS to completely drop the development-only code blocks, reducing final file size.
80+
81+
#### Webpack
82+
83+
Use Webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/):
84+
85+
``` js
86+
var webpack = require('webpack')
87+
88+
module.exports = {
89+
// ...
90+
plugins: [
91+
// ...
92+
new webpack.DefinePlugin({
93+
'process.env': {
94+
NODE_ENV: JSON.stringify('production')
95+
}
96+
})
97+
]
98+
}
99+
```
100+
101+
#### Rollup
102+
103+
Use [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace):
54104
55-
For Browserify, use the [aliasify](https://github.com/benbria/aliasify) transform.
105+
``` js
106+
const replace = require('rollup-plugin-replace')
56107
57-
- ### vue.runtime.js
108+
rollup({
109+
// ...
110+
plugins: [
111+
replace({
112+
'process.env.NODE_ENV': JSON.stringify('production')
113+
})
114+
]
115+
}).then(...)
116+
```
58117
59-
The runtime-only (compiler-excluded) browser build. You can also include this build with a script tag, but with this build, you will **not** be able to use the `template` option. Hard-coded to development mode.
118+
#### Browserify
60119
61-
- ### vue.runtime.min.js
120+
Apply a global [envify](https://github.com/hughsk/envify) transform to your bundle.
62121
63-
Same as `vue.runtime.js`, but minified AND hard-coded to production mode (with runtime checks and warnings stripped).
122+
``` bash
123+
NODE_ENV=production browserify -g envify -e main.js | uglifyjs -c -m > build.js
124+
```

0 commit comments

Comments
 (0)