8000 tweak installation page · biteknight/vuejs.org@08f08c1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 08f08c1

Browse files
yyx990803yyx990803
committed
tweak installation page
1 parent eef91d8 commit 08f08c1

File tree

3 files changed

+156
-43
lines changed

3 files changed

+156
-43
lines changed

‎src/v2/guide/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ If you are an experienced frontend developer and want to know how Vue compares t
1717
The easiest way to try out Vue.js is using the [JSFiddle Hello World example](https://jsfiddle.net/chrisvfritz/50wL7mdz/). Feel free to open it in another tab and follow along as we go through some basic examples. Or, you can simply create an `.html` file and include Vue with:
1818

1919
``` html
20-
<script src="https://unpkg.com/vue/dist/vue.js"></script>
20+
<script src="https://unpkg.com/vue"></script>
2121
```
2222

2323
The [Installation](installation.html) page provides more options of installing Vue. Note that we **do not** recommend beginners to start with `vue-cli`, especially if you are not yet familiar with Node.js-based build tools.

‎src/v2/guide/installation.md

Lines changed: 146 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Vue does **not** support IE8 and below, because it uses ECMAScript 5 features th
1717

1818
Detailed release notes for each version are available on [GitHub](https://github.com/vuejs/vue/releases).
1919

20-
## Standalone
20+
## Direct `<script>` Include
2121

2222
Simply download and include with a script tag. `Vue` will be registered as a global variable.
2323

@@ -31,7 +31,7 @@ Simply download and include with a script tag. `Vue` will be registered as a glo
3131

3232
### CDN
3333

34-
Recommended: [unpkg](https://unpkg.com/vue/dist/vue.js), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [unpkg.com/vue/](https://unpkg.com/vue/).
34+
Recommended: [https://unpkg.com/vue](https://unpkg.com/vue), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [https://unpkg.com/vue/](https://unpkg.com/vue/).
3535

3636
Also available on [jsDelivr](//cdn.jsdelivr.net/vue/latest/vue.js) or [cdnjs](//cdnjs.cloudflare.com/ajax/libs/vue/{{vue_version}}/vue.js), but these two services take some time to sync so the latest release may not be available yet.
3737

@@ -44,58 +44,171 @@ NPM is the recommended installation method when building large scale application
4444
$ npm install vue
4545
```
4646

47-
### Standalone vs. Runtime-only Build
47+
## CLI
48+
49+
Vue.js provides an [official CLI](https://github.com/vuejs/vue-cli) for quickly scaffolding ambitious Single Page Applications. It provides batteries-included build setups for a modern frontend workflow. It takes only a few minutes to get up and running with hot-reload, lint-on-save, and production-ready builds:
50+
51+
``` bash
52+
# install vue-cli
53+
$ npm install --global vue-cli
54+
# create a new project using the "webpack" template
55+
$ vue init webpack my-project
56+
# install dependencies and go!
57+
$ cd my-project
58+
$ npm install
59+
$ npm run dev
60+
```
61+
62+
<p class="tip">The CLI assumes prior knowledge of Node.js and the associated build tools. If you are new to Vue or front-end build tools, we strongly suggest going through <a href="./">the guide</a> without any build tools before using the CLI.</p>
63+
64+
## Explanation of Different Builds
4865

49-
There are two builds available, the standalone build and the runtime-only build. The difference being that the former includes the **template compiler** and the latter does not.
66+
In the [`dist/` directory of the NPM package](https://unpkg.com/vue@latest/dist/) you will find many different builds of Vue.js. Here's an overview of the difference between them:
5067

51-
The template compiler is responsible for compiling Vue template strings into pure JavaScript render functions. If you want to use the `template` option, then you need the compiler.
68+
| | UMD | CommonJS | ES Module |
69+
| --- | --- | --- | --- |
70+
| **Full** | vue.js | vue.common.js | vue.esm.js |
71+
| **Runtime-only** | vue.runtime.js | vue.runtime.common.js | vue.runtime.esm.js |
72+
| **Full (production)** | vue.min.js | - | - |
73+
| **Runtime-only (production)** | vue.runtime.min.js | - | - |
5274

53-
- The standalone build includes the compiler and supports the `template` option. **It also relies on the presence of browser APIs so you cannot use it for server-side rendering.**
75+
### Terms
5476

55-
- The runtime-only build does not include the template compiler, and does not support the `template` option. You can only use the `render` option when using the runtime-only build, but it works with single-file components, because single-file components' templates are pre-compiled into `render` functions during the build step. The runtime-only build is roughly 30% lighter-weight than the standalone build, weighing only {{ro_gz_size}}kb min+gzip.
77+
- **Full**: builds that contains both the compiler and the runtime.
5678

57-
By default, the NPM package exports the **runtime-only** build. To use the standalone build, add the following alias to your Webpack config:
79+
- **Compiler**: code that is responsible for compiling template strings into JavaScript render functions.
80+
81+
- **Runtime**: code that is responsible for creating Vue instances, rendering and patching virtual DOM, etc. Basically everything minus the compiler.
82+
83+
- **[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`).
84+
85+
- **[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`).
86+
87+
- **[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`).
88+
89+
### Runtime + Compiler vs. Runtime-only
90+
91+
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:
5892

5993
``` js
60-
resolve: {
61-
alias: {
62-
'vue$': 'vue/dist/vue.common.js'
94+
// this requires the compiler
95+
new Vue({
96+
template: `<div>{{ hi }}</div>`
97+
})
98+
99+
// this does not
100+
new Vue({
101+
render (h) {
102+
return h('div', this.hi)
103+
}
104+
})
105+
```
106+
107+
When using `vue-loader` or `vueify`, templates inside `*.vue` files are pre-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.
108+
109+
Since the runtime-only builds are roughly 30% lighter-weight than their full-build counterparts, you should use it whenever you can. If you still wish to use the full build instead, you need to configure an alias in your bundler:
110+
111+
#### Webpack
112+
113+
``` js
114+
module.exports = {
115+
// ...
116+
resolve: {
117+
alias: {
118+
'vue$': 'vue/dist/vue.esm.js' // 'vue/dist/vue.common.js' for webpack 1
119+
}
63120
}
64121
}
122+
````
123+
124+
#### Rollup
125+
126+
``` js
127+
const alias = require('rollup-plugin-alias')
128+
129+
rollup({
130+
// ...
131+
plugins: [
132+
alias({
133+
'vue': 'vue/dist/vue.esm.js'
134+
})
135+
]
136+
})
65137
```
66138

67-
For Browserify, you can add an alias to your package.json:
139+
#### Browserify
140+
141+
Add to your project's `package.json`:
68142
69143
``` js
70-
"browser": {
71-
"vue": "vue/dist/vue.common"
72-
},
144+
{
145+
// ...
146+
"browser": {
147+
"vue": "vue/dist/vue.common.js"
148+
}
149+
}
73150
```
74151
75-
<p class="tip">Do NOT do `import Vue from 'vue/dist/vue.js'` - since some tools or 3rd party libraries may import vue as well, this may cause the app to load both the runtime and standalone builds at the same time and lead to errors.</p>
152+
### Development vs. Production Mode
76153
77-
### CSP environments
154+
Development/production modes are hard-coded for the UMD builds: the un-minified files are for development, and the minified files are for production.
78155
79-
Some environments, such as Google Chrome Apps, enforce Content Security Policy (CSP), which prohibits the use of `new Function()` for evaluating expressions. The standalone build depends on this feature to compile templates, so is unusable in these environments.
156+
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.
80157

81-
On the other hand, the runtime-only build is fully CSP-compliant. When using the runtime-only build with [Webpack + vue-loader](https://github.com/vuejs-templates/webpack-simple) or [Browserify + vueify](https://github.com/vuejs-templates/browserify-simple), your templates will be precompiled into `render` functions which work perfectly in CSP environments.
158+
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.
82159

83-
## CLI
160+
#### Webpack
84161

85-
Vue.js provides an [official CLI](https://github.com/vuejs/vue-cli) for quickly scaffolding ambitious Single Page Applications. It provides batteries-included build setups for a modern frontend workflow. It takes only a few minutes to get up and running with hot-reload, lint-on-save, and production-ready builds:
162+
Use Webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/):
163+
164+
``` js
165+
var webpack = require('webpack')
166+
167+
module.exports = {
168+
// ...
169+
plugins: [
170+
// ...
171+
new webpack.DefinePlugin({
172+
'process.env': {
173+
NODE_ENV: JSON.stringify('production')
174+
}
175+
})
176+
]
177+
}
178+
```
179+
180+
#### Rollup
181+
182+
Use [rollup-plugin-replace](https://github.com/rollup/rollup-plugin-replace):
183+
184+
``` js
185+
const replace = require('rollup-plugin-replace')
186+
187+
rollup({
188+
// ...
189+
plugins: [
190+
replace({
191+
'process.env.NODE_ENV': JSON.stringify('production')
192+
})
193+
]
194+
}).then(...)
195+
```
196+
197+
#### Browserify
198+
199+
Apply a global [envify](https://github.com/hughsk/envify) transform to your bundle.
86200
87201
``` bash
88-
# install vue-cli
89-
$ npm install --global vue-cli
90-
# create a new project using the "webpack" template
91-
$ vue init webpack my-project
92-
# install dependencies and go!
93-
$ cd my-project
94-
$ npm install
95-
$ npm run dev
202+
NODE_ENV=production browserify -g envify -e main.js | uglifyjs -c -m > build.js
96203
```
97204
98-
<p class="tip">The CLI assumes prior knowledge of Node.js and the associated build tools. If you are new to Vue or front-end build tools, we strongly suggest going through <a href="./">the guide</a> without any build tools before using the CLI.</p>
205+
Also see [Production Deployment Tips](./deployment.html).
206+
207+
### CSP environments
208+
209+
Some environments, such as Google Chrome Apps, enforce Content Security Policy (CSP), which prohibits the use of `new Function()` for evaluating expressions. The standalone build depends on this feature to compile templates, so is unusable in these environments.
210+
211+
On the other hand, the runtime-only build is fully CSP-compliant. When using the runtime-only build with [Webpack + vue-loader](https://github.com/vuejs-templates/webpack-simple) or [Browserify + vueify](https://github.com/vuejs-templates/browserify-simple), your templates will be precompiled into `render` functions which work perfectly in CSP environments.
99212
100213
## Dev Build
101214
@@ -110,11 +223,13 @@ npm run build
110223

111224
## Bower
112225

226+
Only UMD builds are available from Bower.
227+
113228
``` bash
114229
# latest stable
115230
$ bower install vue
116231
```
117232

118233
## AMD Module Loaders
119234

120-
The standalone downloads or versions installed via Bower are wrapped with UMD so they can be used directly as an AMD module.
235+
All UMD builds can be used directly as an AMD module.

‎themes/vue/source/css/page.styl

Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -99,22 +99,20 @@
9999
iframe
100100
margin 1em 0
101101
> table
102-
border 2px solid $white
102+
border-spacing 0
103+
border-collapse collapse
103104
margin 1.2em auto
104-
padding: 1em
105+
padding 0
105106
td, th
106-
line-height 1.6em
107-
padding .5em 1.4em
107+
line-height 1.5em
108+
padding .4em .8em
108109
border none
109-
td
110-
background-color: lighten($codebg, 60%)
110+
border 1px solid #ddd
111111
th
112-
background-color: $green
113-
color: #fff
114-
padding-top: .85em
115-
padding-bottom .85em
112+
font-weight bold
116113
text-align left
117-
tbody
114+
th, tr:nth-child(2n)
115+
background-color #f8f8f8
118116
code
119117
background-color #efefef
120118
p.tip

0 commit comments

Comments
 (0)
0