diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index e03e3f4fe0..e16ae1cc03 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -53,7 +53,8 @@ const sidebar = {
collapsable: true,
children: ['writing-guide']
}
- ]
+ ],
+ api: ['/api/application-config', '/api/application-api']
}
module.exports = {
@@ -67,6 +68,7 @@ module.exports = {
rel: 'stylesheet',
},
],
+ ['link', { rel: 'icon', href: '/logo.png' }],
[
'script',
{
@@ -92,7 +94,7 @@ module.exports = {
{ text: 'Tooling', link: '/tooling/' }
]
},
- { text: 'API Reference', link: '/api/' },
+ { text: 'API Reference', link: '/api/application-config' },
{
text: 'Examples',
ariaLabel: 'Examples Menu',
@@ -114,8 +116,10 @@ module.exports = {
],
sidebarDepth: 2,
sidebar: {
+ collapsable: false,
'/guide/': sidebar.guide,
- '/community/': sidebar.guide
+ '/community/': sidebar.guide,
+ '/api/': sidebar.api
},
smoothScroll: false
},
diff --git a/src/api/application-api.md b/src/api/application-api.md
new file mode 100644
index 0000000000..a0e800c032
--- /dev/null
+++ b/src/api/application-api.md
@@ -0,0 +1,274 @@
+# Application API
+
+In Vue 3, APIs that globally mutate Vue's behavior are now moved to application instances created by the new `createApp` method. In addition, their effects are now scoped to that specific application's instance:
+
+```js
+import { createApp } from 'vue'
+
+const app = createApp({})
+```
+
+Calling `createApp` returns an application instance. This instance provides an application context. The entire component tree mounted by the application instance share the same context, which provides the configurations that were previously "global" in Vue 2.x.
+
+In addition, since the `createApp` method returns the application instance itself, you can chain other methods after it which can be found in the following sections.
+
+## component
+
+- **Arguments:**
+
+ - `{string} name`
+ - `{Function | Object} [definition]`
+
+- **Usage:**
+
+ Register or retrieve a global component. Registration also automatically sets the component's `name` with the given `name` parameter.
+
+- **Example:**
+
+```js
+import { createApp } from 'vue'
+
+const app = createApp({})
+
+// register an options object
+app.component('my-component', {
+ /* ... */
+})
+
+// retrieve a registered component (always return constructor)
+const MyComponent = app.component('my-component', {})
+```
+
+- **See also:** [Components](../guide/component-basics.html)
+
+## config
+
+- **Usage:**
+
+An object containing application configurations.
+
+- **Example:**
+
+```js
+import { createApp } from 'vue'
+const app = createApp({})
+
+app.config = {...}
+```
+
+- **See also:** [Global Config Properties](./global-config.html)
+
+## directive
+
+- **Arguments:**
+
+ - `{string} name`
+ - `{Function | Object} [definition]`
+
+- **Usage:**
+
+ Register or retrieve a global directive.
+
+- **Example:**
+
+```js
+import { createApp } from 'vue'
+const app = createApp({})
+
+// register
+app.directive('my-directive', {
+ // Directive has a set of lifecycle hooks:
+ // called before bound element's parent component is mounted
+ beforeMount() {},
+ // called when bound element's parent component is mounted
+ mounted() {},
+ // called before the containing component's VNode is updated
+ beforeUpdate() {},
+ // called after the containing component's VNode and the VNodes of its children // have updated
+ updated() {},
+ // called before the bound element's parent component is unmounted
+ beforeUnmount() {},
+ // called when the bound element's parent component is unmounted
+ unmounted() {}
+})
+
+// register (function directive)
+app.directive('my-directive', () => {
+ // this will be called as `mounted` and `updated`
+})
+
+// getter, return the directive definition if registered
+const myDirective = app.directive('my-directive')
+```
+
+Directive hooks are passed these arguments:
+
+#### el
+
+The element the directive is bound to. This can be used to directly manipulate the DOM.
+
+#### binding
+
+An object containing the following properties.
+
+- `instance`: The instance of the component where directive is used.
+- `value`: The value passed to the directive. For example in `v-my-directive="1 + 1"`, the value would be `2`.
+- `oldValue`: The previous value, only available in `beforeUpdate` and `updated`. It is available whether or not the value has changed.
+- `arg`: The argument passed to the directive, if any. For example in `v-my-directive:foo`, the arg would be `"foo"`.
+- `modifiers`: An object containing modifiers, if any. For example in `v-my-directive.foo.bar`, the modifiers object would be `{ foo: true, bar: true }`.
+- `dir`: an object, passed as a parameter when directive is registered. For example, in the directive
+
+```js
+app.directive('focus', {
+ mounted(el) {
+ el.focus()
+ }
+})
+```
+
+`dir` would be the following object:
+
+```js
+{
+ mounted(el) {
+ el.focus()
+ }
+}
+```
+
+#### vnode
+
+A blueprint of the real DOM element received as el argument above. See the [VNode API](TODO) for full details.
+
+#### prevNode
+
+The previous virtual node, only available in the `beforeUpdate` and `updated` hooks.
+
+:::tip Note
+Apart from `el`, you should treat these arguments as read-only and never modify them. If you need to share information across hooks, it is recommended to do so through element's [dataset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset).
+:::
+
+- **See also:** [Custom Directives](../guide/custom-directive.html)
+
+## mixin
+
+- **Arguments:**
+
+ - `{Object} mixin`
+
+- **Usage:**
+
+ Apply a mixin in the whole application scope, which will affect **every** Vue instance created afterwards in the given app (for example, child components). This can be used by plugin authors to inject custom behavior into components. **Not recommended in application code**.
+
+- **See also:** [Global Mixin](../guide/mixins.html#global-mixin)
+
+## mount
+
+- **Arguments:**
+
+ - `{Element | string} rootContainer`
+ - `{boolean} isHydrate`
+
+- **Usage:**
+
+ Mounts a root component of the application instance on the provided DOM element.
+
+- **Example:**
+
+```html
+
+
+
+```
+
+```js
+import { createApp } from 'vue'
+
+const app = createApp({})
+// do some necessary preparations
+app.mount('#my-app')
+```
+
+- **See also:**
+ - [Lifecycle Diagram](../guide/instance.html#lifecycle-diagram)
+
+## provide
+
+- **Type:**
+
+ - `Object | () => Object`
+
+- **Details:**
+
+ This option is used together with [`inject`](TODO:inject) are used together to allow an ancestor component to serve as a dependency injector for all its descendants, regardless of how deep the component hierarchy is, as long as they are in the same parent chain.
+
+ The `provide` option should be an object or a function that returns an object. This object contains the properties that are available for injection into its descendants. You can use ES2015 Symbols as keys in this object, but only in environments that natively support `Symbol` and `Reflect.ownKeys`.
+
+ > Note: the `provide` and `inject` bindings are NOT reactive. This is intentional. However, if you pass down an observed object, properties on that object do remain reactive.
+
+- **Example:**
+
+```js
+import { createApp } from 'vue'
+
+const app = createApp({
+ provide: {
+ user: 'John Doe'
+ }
+})
+
+app.component('user-card', {
+ inject: ['user'],
+ template: `
+
+ {{ user }}
+
+ `
+})
+```
+
+- **See also:**
+ - [Provide / Inject](../guide/component-provide-inject.md)
+
+## unmount
+
+- **Arguments:**
+
+ - `{Element | string} rootContainer`
+
+- **Usage:**
+
+ Unmounts a root component of the application instance on the provided DOM element.
+
+- **Example:**
+
+```html
+
+
+
+```
+
+```js
+import { createApp } from 'vue'
+
+const app = createApp({})
+// do some necessary preparations
+app.mount('#my-app')
+
+// Application will be unmounted 5 seconds after mount
+setTimeout(() => app.unmount('#my-app'), 5000)
+```
+
+## use
+
+- **Arguments:**
+
+ - `{Object | Function} plugin`
+
+- **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.
+
+ When this method is called on the same plugin multiple times, the plugin will be installed only once.
+
+- **See also:** [Plugins](TODO)
diff --git a/src/api/application-config.md b/src/api/application-config.md
new file mode 100644
index 0000000000..b38191c183
--- /dev/null
+++ b/src/api/application-config.md
@@ -0,0 +1,149 @@
+# Application Config
+
+`config` is an object containing Vue application global configurations. You can modify its properties listed below before mounting your application:
+
+```js
+const app = Vue.createApp({})
+
+app.config = {...}
+```
+
+## devtools
+
+- **Type:** `boolean`
+
+- **Default:** `true` (`false` in production builds)
+
+- **Usage:**
+
+```js
+app.config.devtools = true
+```
+
+Configure whether to allow [vue-devtools](https://github.com/vuejs/vue-devtools) inspection. This option's default value is `true` in development builds and `false` in production builds. You can set it to `true` to enable inspection for production builds.
+
+## errorHandler
+
+- **Type:** `Function`
+
+- **Default:** `undefined`
+
+- **Usage:**
+
+```js
+app.config.errorHandler = (err, vm, info) => {
+ // handle error
+ // `info` is a Vue-specific error info, e.g. which lifecycle hook
+ // the error was found in
+}
+```
+
+Assign a handler for uncaught errors during component render function and watchers. The handler gets called with the error and the Vue instance.
+
+> Error tracking services [Sentry](https://sentry.io/for/vue/) and [Bugsnag](https://docs.bugsnag.com/platforms/browsers/vue/) provide official integrations using this option.
+
+## warnHandler
+
+- **Type:** `Function`
+
+- **Default:** `undefined`
+
+- **Usage:**
+
+```js
+app.config.warnHandler = function(msg, vm, trace) {
+ // `trace` is the component hierarchy trace
+}
+```
+
+Assign a custom handler for runtime Vue warnings. Note this only works during development and is ignored in production.
+
+## globalProperties
+
+- **Type:** `[key: string]: any`
+
+- **Default:** `undefined`
+
+- **Usage:**
+
+```js
+app.config.globalProperties.foo = 'bar'
+
+app.component('child-component', {
+ mounted() {
+ console.log(this.foo) // 'bar'
+ }
+})
+```
+
+Adds a global property that can be accessed in any component instance inside the application. The component’s property will take priority when there are conflicting keys.
+
+This can replace Vue 2.x `Vue.prototype` extending:
+
+```js
+// Before
+Vue.prototype.$http = () => {}
+
+// After
+const app = Vue.createApp({})
+app.config.globalProperties.$http = () => {}
+```
+
+## isCustomElement
+
+- **Type:** `(tag: string) => boolean`
+
+- **Default:** `undefined`
+
+- **Usage:**
+
+```js
+// any element starting with 'ion-' will be recognized as a custom one
+app.config.isCustomElement = tag => tag.startsWith('ion-')
+```
+
+Specifies a method to recognize custom elements defined outside of Vue (e.g., using the Web Components APIs). If component matches this condition, it won't need local or global registration and Vue won't throw a warning about an `Unknown custom element`.
+
+> Note that all native HTML and SVG tags don't need to be matched in this function - Vue parser performs this check automatically
+
+## optionMergeStrategies
+
+- **Type:** `{ [key: string]: Function }`
+
+- **Default:** `{}`
+
+- **Usage:**
+
+```js
+const app = Vue.createApp({
+ mounted() {
+ console.log(this.$options.hello)
+ }
+})
+
+app.config.optionMergeStrategies.hello = (parent, child, vm) => {
+ return `Hello, ${child}`
+}
+
+app.mixin({
+ hello: 'Vue'
+})
+
+// 'Hello, Vue
+```
+
+Define merging strategies for custom options.
+
+The merge strategy receives the value of that option defined on the parent and child instances as the first and second arguments, respectively. The context Vue instance is passed as the third argument.
+
+- **See also:** [Custom Option Merging Strategies](../guide/mixins.html#custom-option-merge-strategies)
+
+## performance
+
+- **Type:** `boolean`
+
+- **Default:** `false`
+
+- **Usage**:
+
+Set this to `true` to enable component init, compile, render and patch performance tracing in the browser devtool performance/timeline panel. Only works in development mode and in browsers that support the [performance.mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) API.
diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md
index 6d36059611..8d89faddb2 100644
--- a/src/guide/component-basics.md
+++ b/src/guide/component-basics.md
@@ -395,7 +395,7 @@ See [this sandbox](https://codepen.io/team/Vue/pen/oNXaoKy) to experiment with t
Keep in mind that this attribute can be used with regular HTML elements, however they will be treated as components, which means all attributes **will be bound as DOM attributes**. For some properties such as `value` to work as you would expect, you will need to bind them using the [`.prop` modifier](TODO:../api/#v-bind).
-That's all you need to know about dynamic components for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Dynamic & Async Components](TODO:components-dynamic-async.html).
+That's all you need to know about dynamic components for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Dynamic & Async Components](components-dynamic-async).
## DOM Template Parsing Caveats
@@ -444,4 +444,4 @@ It should be noted that **these limitations does _not_ apply if you are using st
That's all you need to know about DOM template parsing caveats for now - and actually, the end of Vue's _Essentials_. Congratulations! There's still more to learn, but first, we recommend taking a break to play with Vue yourself and build something fun.
-Once you feel comfortable with the knowledge you've just digested, we recommend coming back to read the full guide on [Dynamic & Async Components](TODO:components-dynamic-async.html), as well as the other pages in the Components In-Depth section of the sidebar.
+Once you feel comfortable with the knowledge you've just digested, we recommend coming back to read the full guide on [Dynamic & Async Components](components-dynamic-async), as well as the other pages in the Components In-Depth section of the sidebar.
diff --git a/src/guide/custom-directive.md b/src/guide/custom-directive.md
index 563aead6c7..e083e04e10 100644
--- a/src/guide/custom-directive.md
+++ b/src/guide/custom-directive.md
@@ -66,7 +66,7 @@ We'll cover VNodes in more detail [later](TODO:/render-function.html#The-Virtual
- `unmounted`: called only once, when the directive is unbound from the element and the parent component is unmounted.
-You can check the arguments passed into these hooks (i.e. `el`, `binding`, `vnode`, and `prevVnode`) in [Custom Directive API](TODO)
+You can check the arguments passed into these hooks (i.e. `el`, `binding`, `vnode`, and `prevVnode`) in [Custom Directive API](../api/global-api.html#directive)
### Dynamic Directive Arguments
diff --git a/src/guide/mixins.md b/src/guide/mixins.md
index 48df8b3b68..b0cbe035a1 100644
--- a/src/guide/mixins.md
+++ b/src/guide/mixins.md
@@ -154,7 +154,7 @@ app.component('test-component', {
myOption: 'hello from component!'
})
-app.mount('##mixins-global')
+app.mount('#mixins-global')
// => "hello!"
// => "hello from component!"
@@ -169,7 +169,7 @@ When custom options are merged, they use the default strategy which overwrites t
```js
const app = Vue.createApp({})
-app.config.optionMergeStrategies.customOption = (toVal, fromVal) {
+app.config.optionMergeStrategies.customOption = (toVal, fromVal) => {
// return mergedVal
}
```