2.0 Docs

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

[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.