App-Wide Plugins

## What a plugin is In Vue 3 an **application instance** is created with `createApp(App)`. Everything that should apply to the whole app, rather than to one component, is registered on that instance. A **plugin** is a reusable bundle of such registrations. Vue accepts two shapes: - an **object plugin**: any object with an `install(app, ...options)` method; - a **function plugin**: a bare function `(app, ...options) => void`, which Vue calls as if it were `install`. There is no base class and nothing to extend. If the value passed to `app.use` is neither a function nor an object with an `install` function, Vue does nothing and, in development, warns: *A plugin must either be a function or an object with an "install" function.* ## What app.use does, step by step The implementation lives in `createApp` in `runtime-core`. When you call `app.use(plugin, ...options)`: 1. Vue checks a per-app set of already-installed plugins. If this exact plugin object or function is in it, the call is skipped and development builds warn *Plugin has already been applied to target app.* 2. Otherwise, if `plugin.install` is a function, Vue records the plugin and calls `plugin.install(app, ...options)`. 3. Otherwise, if the plugin itself is a function, Vue records it and calls `plugin(app, ...options)`. 4. Vue returns `app`, so `createApp(App).use(a).use(b, opts).mount('#app')` chains naturally. Two details follow from that code. The return value of `install` is **ignored**, so an `async install` is not awaited: `app.use` returns before its promise settles. And the installed set belongs to **one app**: the same plugin used on two different apps runs twice, once against each. ## What an install function usually registers | API used inside install | What it adds | Where it is reached | |---|---|---| | `app.component(name, comp)` | a globally registered component | any template in the app | | `app.directive(name, dir)` | a globally registered custom directive | any template in the app | | `app.provide(key, value)` | an app-level injectable value | `inject(key)` in any component of the app | | `app.config.globalProperties.$x = ...` | a property on every component instance | templates and Options API `this` | A plugin may do any combination of these, and it may read `app.version` to branch on the Vue version it is installed into. ## Timing: configure first, then mount Plugins are ordinary synchronous setup code, so **order matters**: - Call every `app.use` before `app.mount()`. The first render resolves global components and directives and reads global properties, so anything registered later misses that render. - Remember that `app.mount()` returns the **root component instance**, not the app. `createApp(App).mount('#app').use(plugin)` fails because the value returned by mount has no `use` method. - If a plugin needs asynchronous data before the first render, load it before calling `mount`, rather than hoping `app.use` waits. ## How this differs from Vue 2 In Vue 2, `Vue.use(plugin)` mutated the **global** Vue constructor, so every instance on the page received the plugin, and there was no way to undo it. Vue 3 replaced that with `app.use`, scoped to a single app instance. Two apps on one page can therefore install different plugins, or the same plugin with different options, without interfering with each other. ## Where plugins meet the rest of the app A plugin normally does not touch components directly. It writes into the app's **context**, the per-app record that holds registered components, directives, provides and config. Every component created under that app receives a reference to the same context, which is why one `app.use` call in `main.ts` is visible everywhere in the tree and nowhere outside it. Consequences worth being able to explain: - **Tests.** A component test that needs a plugin must install it on the test's own app; the `app.use` in `main.ts` is not involved, because the test builds a different app. - **Order between plugins.** Plugins run in the order of the `use` calls, so a plugin that depends on something another plugin registered must be installed after it. - **Options are captured at install.** The options passed to `app.use` configure the plugin for that app; mutating the object later matters only if the plugin reads it lazily. - **Registrations are named.** Registering a component or directive under a name already taken on the app overwrites the earlier one, and development builds warn about the duplicate. ## Common mistakes - Treating `app.use` as page-global: it only affects the app it is called on. - Expecting a second `app.use(samePlugin, newOptions)` to reconfigure the plugin: it is skipped. - Writing `async install()` and assuming the app waits for it. - Chaining `.use()` after `.mount()`. - Confusing Vue app plugins with bundler plugins, which run at build time and never see the app instance.