diff --git a/src/v2/api/index.md b/src/v2/api/index.md index c267bfafcc..c145fe0d09 100644 --- a/src/v2/api/index.md +++ b/src/v2/api/index.md @@ -361,6 +361,8 @@ type: api - **Usage:** Install a Vue.js plugin. If the plugin is an Object, it must expose an `install` method. If it is a function itself, it will be treated as the install method. The install method will be called with Vue as the argument. + + This method has to be called before calling `new Vue()` When this method is called on the same plugin multiple times, the plugin will be installed only once. diff --git a/src/v2/guide/plugins.md b/src/v2/guide/plugins.md index 13c6dd1ebb..ef9363bb39 100644 --- a/src/v2/guide/plugins.md +++ b/src/v2/guide/plugins.md @@ -4,9 +4,7 @@ type: guide order: 304 --- -## Writing a Plugin - -Plugins usually add global-level functionality to Vue. There is no strictly defined scope for a plugin - there are typically several types of plugins you can write: +Plugins usually add global-level functionality to Vue. There is no strictly defined scope for a plugin - there are typically several types of plugins: 1. Add some global methods or properties. e.g. [vue-custom-element](https://github.com/karol-f/vue-custom-element) @@ -18,6 +16,42 @@ Plugins usually add global-level functionality to Vue. There is no strictly defi 5. A library that provides an API of its own, while at the same time injecting some combination of the above. e.g. [vue-router](https://github.com/vuejs/vue-router) +## Using a Plugin + +Use plugins by calling the `Vue.use()` global method. This has to be done before you start your app by calling `new Vue()`: + +``` js +// calls `MyPlugin.install(Vue)` +Vue.use(MyPlugin) + +new Vue({ + //... options +}) +``` + +You can optionally pass in some options: + +``` js +Vue.use(MyPlugin, { someOption: true }) +``` + +`Vue.use` automatically prevents you from using the same plugin more than once, so calling it multiple times on the same plugin will install the plugin only once. + +Some plugins provided by Vue.js official plugins such as `vue-router` automatically calls `Vue.use()` if `Vue` is available as a global variable. However in a module environment such as CommonJS, you always need to call `Vue.use()` explicitly: + +``` js +// When using CommonJS via Browserify or Webpack +var Vue = require('vue') +var VueRouter = require('vue-router') + +// Don't forget to call this +Vue.use(VueRouter) +``` + +Checkout [awesome-vue](https://github.com/vuejs/awesome-vue#components--libraries) for a huge collection of community-contributed plugins and libraries. + +## Writing a Plugin + A Vue.js plugin should expose an `install` method. The method will be called with the `Vue` constructor as the first argument, along with possible options: ``` js @@ -49,33 +83,3 @@ MyPlugin.install = function (Vue, options) { } } ``` - -## Using a Plugin - -Use plugins by calling the `Vue.use()` global method: - -``` js -// calls `MyPlugin.install(Vue)` -Vue.use(MyPlugin) -``` - -You can optionally pass in some options: - -``` js -Vue.use(MyPlugin, { someOption: true }) -``` - -`Vue.use` automatically prevents you from using the same plugin more than once, so calling it multiple times on the same plugin will install the plugin only once. - -Some plugins provided by Vue.js official plugins such as `vue-router` automatically calls `Vue.use()` if `Vue` is available as a global variable. However in a module environment such as CommonJS, you always need to call `Vue.use()` explicitly: - -``` js -// When using CommonJS via Browserify or Webpack -var Vue = require('vue') -var VueRouter = require('vue-router') - -// Don't forget to call this -Vue.use(VueRouter) -``` - -Checkout [awesome-vue](https://github.com/vuejs/awesome-vue#components--libraries) for a huge collection of community-contributed plugins and libraries.