2.0 Docs

[chrisvfritz]

Guidelines for writing official Vue docs

These are not immutable dictates, but rather a place to consolidate our evolving consensus. If there's an item you strongly disagree with, please do discuss it below and this section will be updated to better explain and reflect the new consensus.

• Use 2-space indentation in examples for all languages.
• Use only ES5 features in JavaScript examples unless the example already requires a build process or demonstrates a plugin that is almost exclusively used in applications complex enough to warrant a build process (e.g. vuex or vue-router).
• Adhere to ferross/standard in JavaScript examples.
• Adhere to Google's style guide for HTML and CSS. You probably don't have to actually read it, because wildly diverging styles are less common in these languages, but this resource can be used to end bikeshedding.
• Use el: '#app' in place of el: 'body' to encourage the thinking that you are able to limit Vue's scope on your page.
• Use JSFiddle exclusively for embedded and linked demos. The only exception is WebpackBin may be used to demonstrate code that requires a build step, such as the .vue file syntax or JSX.
• Use https://unpkg.com/vue@next/dist/vue.js to reference Vue 2.0 in all fiddles.
• Use CDN links with hardcoded versions to reference companion libraries.
• Reference linked resources that do not yet exist with !!TODO: ... in place of the URL. The !! prefix makes them distinguishable from todo list examples in a search. 😛
• When referencing the library, use Vue.js in page titles and Vue for every subsequent mention.
• When referencing companion libraries, use the name on GitHub and NPM (e.g. vue-router rather than Vue Router or VueRouter).

### Contributing 1. Edit this comment to change `unclaimed` to `@yourUsername` so everyone knows you're working on a file. 2. Commit directly to the `2.0` branch 3. Try to edit only one file (the one you claimed) at a time. 4. When ready to push, `git fetch origin 2.0`, `git rebase origin/2.0`, then `git push origin 2.0`. (Yes, we're skipping code review for now. Let's just get something in place for this first pass.) 5. Update this comment to put a check next to the file you updated. ### Guide Updates

This list is incomplete and only represents the first pass we'll make in rewriting the docs for 2.0. It's very likely we'll want to remove/add/reorganize many pages and sections. As more issues become apparent in the process of writing docs, we can discuss them here in this issue.

• @chrisvfritz 0. Installation
• @chrisvfritz 1. Getting Started
• @chrisvfritz 2. Overview
• @chrisvfritz 3. The Vue Instance
• @posva 4. Data Binding Syntax
• @chrisvfritz 5. Computed Properties
• @chrisvfritz 6. Class and Style Bindings
• @chrisvfritz 7. Conditional Rendering
• @chrisvfritz 8. List Rendering
• @chrisvfritz 9. Methods and Events Handling
• @chrisvfritz 10. Form Input Bindings
• @chrisvfritz 11. Transitions
• @chrisvfritz 12. Components
• @chrisvfritz 13. Reactivity
• @chrisvfritz 14. Custom Directives
• @chrisvfritz 15. Custom Filters
• @posva 16. Mixins
• @kazupon 17. Plugins
• @chrisvfritz 18. Building Large-Scale Apps. This is being split up into several sections:
  • Single-File Components
  • Routing
  • State Management
  • Unit Testing
• @chrisvfritz 19. Comparison with Other Frameworks
• @chrisvfritz 20. Join the Vue Community!
• @chrisvfritz render functions
  • VNode API ^{moved to API section}
• @chrisvfritz Server-Side Rendering
• Integrating vue-router, vuex, and vue-server-renderer ^{SSR docs link to documentation and examples for this}
• @chrisvfritz 1.0 Migration Guide

Misc topics that need better coverage

• @chrisvfritz v-once
• @chrisvfritz how to do <script type="text/x-template" id="foo"> with template: '#foo'
• v-cloak ^{not very frequently used, so probably fine to just be in API doc}
• v-pre ^{not very frequently used, so probably fine to just be in API doc}
• @chrisvfritz ref in non-v-for contexts?

### API Updates

Resources:

• Changes Issue
• Updated Guide
• Feature Unit Tests
• Flow Types

Sections:

• @fadymak Global Config
• @fadymak Global API
• Instance Options
  • @fadymak Data
  • @fadymak DOM
  • @fadymak Lifecycle Hooks
  • @fadymak Assets
  • @fadymak Misc
• @kazupon Instance Properties
• Instance Methods
  • @kazupon Data
  • @kazupon Events
  • @kazupon DOM
  • @kazupon Lifecycle
• @kazupon Directives
• @kazupon Special Elements
• @yyx990803 Special Attributes
• unclaimed VNode just point to vnode source
• unclaimed Server-Side Rendering just point to GitHub

[yyx990803]

Re using el: body: let's keep them to ids. I want to encourage the thinking that you are able to limit Vue's scope on your page.

[chrisvfritz]

@yyx990803 👍 Updated the guidelines.

[zigomir]

I went over 2. Overview I think everything still holds for Vue 2.0. Examples work fine. One thing I'm not really sure is if Vue 2.0 is also supporting IE9 and above? If that's true then we might not need to change anything in overview.md file.

[chrisvfritz]

@zigomir I just went through the Overview section and mostly just added more links, but it did indeed need very little change. 😃

[chrisvfritz]

@yyx990803 In writing some documentation for lifecycle hooks, it occurred to me that all of them are in pairs (e.g. beforeMount/mounted and beforeDestroy/destroyed), except for init and created. What would you think about renaming init to beforeCreate for consistency? That may also make it more obvious that at this stage, nothing has actually been initialized.

[zkwolf]

In computed.md line 72, it should be vm.message = 'Goodbye'

[chrisvfritz]

@zkwolf Thanks!! Good catch. 😄 Just fixed it.

[zkwolf]

@chrisvfritz And ... In list.md Object v-for section, you forget change val to value

[chrisvfritz]

@zkwolf Woohoo! Fixed. 😃 Thanks again for your excellent eye.

[chrisvfritz]

@yyx990803 Is there a way to add new keyCode aliases in 2.0? The only gettable directives seem to be model and show.

[chrisvfritz]

@yyx990803 Also, it looks like transition no longer applies a -transition class. I didn't see this explicitly listed as a planned deprecation, so double checking. Should users just add their own always-on class if they want one?

[yyx990803]

@chrisvfritz yeah, overlooked the custom keyCodes usage. Implemented in vuejs/vue@4fe51a7. It is now exposed as Vue.config.keyCodes.

Yes, transition no longer applies the automatic class. The user can either provide the always-on class themselves, or define the transition property in enter-active/leave-active classes.

[MeiYuanChen]

1.vue-server-renderer can solve 'seo' question?
2.Why not ’Guidelines Vue docs‘ inside vue-server-renderer?

[chrisvfritz]

@MeiYuanChen Moving all the docs into a Vue app would take a lot of time to port and the advantages wouldn't be that significant at this point. Hexo is working for us just fine for now. 😃

[zkwolf]

In forms.md line185, it should be <span>Selected: {{ selected }}</span>

[chrisvfritz]

@zkwolf Another excellent catch! Fixed.

[cezaraugusto]

Hi Vue team, two questions:

1. Are those docs open for outside contributors? If so, is the above steps mentioned by @chrisvfritz enough to contribute? Is there something else?
2. If I plan to translate the current documentation: would it be better to wait until 2.0? Is it a breaking version or just improvements? Which things should I be aware of?

Regards

[chrisvfritz]

Hi @cezaraugusto! Great questions. 😃

1. Feedback is definitely welcome, but major contributions from outside the core team won't be practical until the first draft rewrites have all been done. The reason is that a lot of internal discussions are fueling the rewrite, which then often lead to API changes, which then lead to more rewrites. 😜 For the docs that already have a check mark next to them, the first draft has been completed and @zkwolf and others have already found a lot of room for improvement. If you also want to look them over, we'd love to hear your thoughts.
2. For translation, I would probably wait until Vue reaches at least the RC stage, when the API will be very stable and the source documentation will be much less likely to drastically change.

Let me know if that fully addresses your questions.

[cezaraugusto]

Sure @chrisvfritz, thanks for clarifying. Great job so far 👌 , am following closely 👀 .

[theotherzach]

Use only ES5 features in JavaScript examples unless the example already requires a build process or demonstrates a plugin that is almost exclusively used in applications complex enough to warrant a build process (e.g. vuex or vue-router).

Thank you so, so, so, so, so, so, so, so, so, so, so, SO very much for this. I teach Vue to people as an introduction to frontend JavaScript, often in programming communities with little to no culture of JS tooling, so this is huge for me. Thank you thank you thank you thank you thank you.

[miljan-aleksic]

@chrisvfritz, should I open a ticket about issues I found or comment them here first?

[chrisvfritz]

@miljan-aleksic You can just comment here. Thanks for your help!

[dan-gamble]

All i can say after cloning and running this is wow! Absolutely awesome job on the new docs and Vue 2 overall and i've only read the new transition page so far..

[blocka]

I would like to point out two things in comparison docs...I hope this is right place for this.
The first is the claim that "React has made strides in this area, but has yet to produce a production-ready, out-of-the-box solution for new projects." Actually, react as something like this, called "create-react-app", which is certainly production ready. Perhaps there should be a comparison between vue-cli and create-react-app?

The second is the issue with if statements vs ternary statements in jsx. While this is definitely an issue, there is a solution on the horizon, in the form of do expressions. With do expressions, a if/else can be wrapped into one expression and used in JSX (or in array functions for that matter), which makes the syntax a tiny bit more palatable.

For example:

<div className='myComponent'>
    {do {
      if(color === 'blue') { <BlueComponent/>; }
      if(color === 'red') { <RedComponent/>; }
      if(color === 'green') { <GreenComponent/>; }
    }}
  </div>

There is still "syntax tax", but it's definitely nicer looking then hoisting or using ternaries.

[chrisvfritz]

@blocka Thanks for taking a look at this! The comparisons section is definitely something the team will be discussing in more detail before the final release. Regarding those specific items:

Production use of create-react-app

We're aware of this project, but even their documentation only recommends it for getting started with React. It's currently missing many features vital for non-trivial projects, most notably the lack of support for any testing, CSS preprocessors, ES7/2016 features such as the object spread operator and decorators (both are often used quite extensively within React projects), and hot module reloading.

If I were starting a new React project today, I can't think of a scenario where I would use it - and even if I were forced to, I'd have to immediately eject and modify the build process before any significant work could begin.

I think adding a note to let people know we are aware of this project would be good though. 👍

Do expressions for cleaner JSX

I'm definitely excited about do expressions. They'll help a little, but they're currently at stage 0, which is a little more unstable than many projects are willing to work with at this point. I'll add a note about them nonetheless.

[gaearon]

We're aware of this project, but even their documentation only recommends it for getting started with React.

This is not the case. It is explicitly labeled “production-ready”. Yes, it is currently catered more to beginners than to advanced users, but even advanced users find it useful:

(This is from the post-eject survey.)

It's currently missing many features vital for non-trivial projects, most notably the lack of support for

any testing

The support for testing has been merged, and while we may tweak a few things before releasing it officially, it is going to be added. I believe README explicitly says we intend to add testing.

CSS preprocessors

You can run your existing preprocessors just fine if you want to, and import resulting css files. We don’t intend them to be part of the default setup but they’re perfectly usable from create-react-app, with the same workflow that people have been using for years.

ES7/2016 features such as the object spread operator

This is incorrect, spread operator has been supported from the very first release.

and decorators (both are often used quite extensively within React projects)

Decorators are currently not officially supported by Babel, have weird hard-to-diagnose issues, and the spec is still changing. In my experience many people get confused by decorators, and I’m not comfortable including them while they are so unstable in practice.

and hot module reloading.

It’s enabled for CSS, but hot reloading for React components is currently too flaky. (I hope I qualify to speak about that 😄 .)

We care about providing the complete cohesive experience, not just picking the latest popular things. So yes, we leave something out, but we do it on purpose, and not because the tool is half-baked.

[chrisvfritz]

Thanks for the input @gaearon! This is definitely helpful in making sure we don't misrepresent the create-react-app project. 😃 Some quick notes:

• Object Spread Operator: The support for the object spread operator was definitely a misreading on my part - I apologize for that.
• CSS Preprocessors: I would personally prefer not to maintain multiple parallel build systems, but I can see your point that it is possible.
• Production-Ready vs Development-Ready: I did see that it's ready for production and I don't dispute that. The question for me was more whether it was development-ready. With some of the missing features, it wouldn't (currently) be possible for me to generate a new client project and start coding right away, like I can with vue-cli's Webpack template. I'd have to first eject and spend considerable time enhancing the build process and development environment. The addition of out-of-the-box testing goes most of the way in resolving this though, so I'll write assuming it'll be included by the time these docs are released.

Project Goals

I think this is a misconception that could be resolved by updates to the README. My understanding that it was mainly intended for onboarding came from the "Why Use This?" section, which starts with "If you’re getting started with React [...]" - the bolding is not mine.

Testing Support

Glad to hear that it's on the way!

believe README explicitly says we intend to add testing.

I didn't see any explicit mention of this. The section I think you may be referring to contains 3 qualifiers (italics are mine):

Some of them might get added in the future if they are stable, are useful to majority of React apps, don't conflict with existing tools, and don't introduce additional configuration.

This doesn't convey a sense of inevitability to me, but a tweaking to the wording in the first clause might be helpful if you wish to - something like: "We're actively working on the features above and they will be added when [...]".

Thanks Again 😄

Thanks again for the feedback! As we revise this section a little more, I'll be sure to mention/tweet you so you can take another look.

[gaearon]

Thanks for the feedback. We’ll tweak messaging as we get to 1.0 and make this thing more official.

[VyaWave]

Good,Good,But Where is The Chinese Docs ? ? ? @yyx990803

[chrisvfritz]

@AyaMeng As far as I know, translation to Chinese hasn't started yet. When it does, would you like to help?

[smithb1994]

At https://rc.vuejs.org/guide/components.html#Form-Input-Components-using-Custom-Events please consider rewriting the last example from:

template: '\
    <div class="form-group">\
      <label v-bind:for="randomId">{{ label }}:</label>\
      <input v-bind:id="randomId" v-bind:value="value" v-on:input="onInput">\
    </div>\
  '

and change it to a more readable:

template:
    '<div class="form-group">' +
      '<label v-bind:for="randomId">{{ label }}:</label>' +
      '<input v-bind:id="randomId" v-bind:value="value" v-on:input="onInput">' +
    '</div>'

Thanks

[blocka]

Even better

template:
    `<div class="form-group">
      <label v-bind:for="randomId">{{ label }}:</label>
      <input v-bind:id="randomId" v-bind:value="value" v-on:input="onInput">
    </div>`

unless for some reason es6 is avoided in the docs.

[smithb1994]

Similar template readability complaint at https://rc.vuejs.org/guide/components.html#Components-and-v-for

[smithb1994]

At https://rc.vuejs.org/guide/components.html#Async-Components do components accept a returned promise? It didn't indicate whether it did.

[smithb1994]

Same template complaint at https://rc.vuejs.org/guide/components.html#Cheap-Static-Components-with-v-once as well.

[LinusBorg]

@blocka: we use ES5 in the guide (See the second bullet point in the OP), so no template strings.

@smithb1994 Personally, I don't think your way of writing the template is nessessarily more readable, but we will see how he others feel about it.

[smithb1994]

There is no lifecycle diagram at https://rc.vuejs.org/guide/instance.html#Lifecycle-Diagram

[chrisvfritz]

@smithb1994

• Template style: It sounds like just a matter of preference (and your version actually has more syntax characters), so we won't be changing it for now.
• Lifecycle diagram: We are aware. These docs are work-in-progress and if you look at the src for the missing image, you'll actually see !!TODO: EVAN WILL NEED TO UPDATE /images/lifecycle.png. 😉
• Promises with Async Components: You cannot return a promise in async components. The described interface is the only one available. You can still easily use a promise like this though. Edit: Evan just added this feature to rc4. 😃

[chay22]

Few lines under here (on list) tells slots as in context, contains slot object while I have to call it as a function first to get the object returned. Am I missing something?

Also for the lack of directives in #render() is good to mention, too. Something like, here on the second line of first paragraph.

For example, the lack of use of Vue built-in directives in render functions forv-if and v-for as in template:

[hasssan]

Incorrect command in Guide: Coditional and Loops section:

"In the console, enter app3.todos.push({ text: 'New item' })"
should be:
"In the console, enter app4.todos.push({ text: 'New item' })"

[chrisvfritz]

@chay22 You're not missing anything - slots is indeed a function that returns a slots object within functional components. The docs have now been updated to reflect that. As for the directives, it's not universally true no directives are allowed in render functions. For example, v-on has the on equivalent. It's really only when for directives or other Vue features that can be easily replaced with simple JavaScript.

@hasssan Thanks! Fixed the typo.

[jbruni]

@chrisvfritz @yyx990803

vm.$el documentation at https://github.com/vuejs/vuejs.org/blob/2.0/src/api/index.md#vmel

currently says

The DOM element that the Vue instance is managing. vm.$el will return a DOM element that created with the Vue instance.

The first sentence is ok. The second sentence needs to be rephrased.

(Sorry, I don't have a good suggestion. I would have made a PR if I had.)

Thank you.

[chrisvfritz]

@jbruni Thanks, fixed!

[chrisvfritz]

We're locking this thread for now, as the discussion part of the docs is pretty much done now. We still welcome continued feedback in the form of new issues though! 😃

[chrisvfritz]

The core docs are now officially complete! We'll continue to improve them, but everything should have basic coverage.