1 | ## Explanation of Build Files
|
2 |
|
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 | | |
|
9 |
|
10 | ### Terms
|
11 |
|
12 | - **Full**: builds that contains both the compiler and the runtime.
|
13 |
|
14 | - **Compiler**: code that is responsible for compiling template strings into JavaScript render functions.
|
15 |
|
16 | - **Runtime**: code that is responsible for creating Vue instances, rendering and patching virtual DOM, etc. Basically everything minus the compiler.
|
17 |
|
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`).
|
19 |
|
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`).
|
21 |
|
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`).
|
23 |
|
24 | ### Runtime + Compiler vs. Runtime-only
|
25 |
|
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.
|
27 |
|
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.
|
29 |
|
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.
|
31 |
|
32 | #### Webpack
|
33 |
|
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 | ```
|
44 |
|
45 | #### Rollup
|
46 |
|
47 | ``` js
|
48 | const alias = require('rollup-plugin-alias')
|
49 |
|
50 | rollup({
|
51 | // ...
|
52 | plugins: [
|
53 | alias({
|
54 | 'vue': 'vue/dist/vue.esm.js'
|
55 | })
|
56 | ]
|
57 | })
|
58 | ```
|
59 |
|
60 | #### Browserify
|
61 |
|
62 | Add to your project's `package.json`:
|
63 |
|
64 | ``` js
|
65 | {
|
66 | // ...
|
67 | "browser": {
|
68 | "vue": "vue/dist/vue.common.js"
|
69 | }
|
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):
|
104 |
|
105 | ``` js
|
106 | const replace = require('rollup-plugin-replace')
|
107 |
|
108 | rollup({
|
109 | // ...
|
110 | plugins: [
|
111 | replace({
|
112 | 'process.env.NODE_ENV': JSON.stringify('production')
|
113 | })
|
114 | ]
|
115 | }).then(...)
|
116 | ```
|
117 |
|
118 | #### Browserify
|
119 |
|
120 | Apply a global [envify](https://github.com/hughsk/envify) transform to your bundle.
|
121 |
|
122 | ``` bash
|
123 | NODE_ENV=production browserify -g envify -e main.js | uglifyjs -c -m > build.js
|
124 | ```
|