1---
2title: Vue Plugin Best Practices
3impact: MEDIUM
4impactDescription: Incorrect plugin structure or injection key strategy causes install failures, collisions, and unsafe APIs
5type: best-practice
6tags: [vue3, plugins, provide-inject, typescript, dependency-injection]
7---
8 
9# Vue Plugin Best Practices
10 
11**Impact: MEDIUM** - Vue plugins should follow the `app.use()` contract, expose explicit capabilities, and use collision-safe injection keys. This keeps plugin setup predictable and composable across large apps.
12 
13## Task List
14 
15- Export plugins as an object with `install()` or as an install function
16- Use the `app` instance in `install()` to register components/directives/provides
17- Type plugin APIs with `Plugin` (and options tuple types when needed)
18- Use symbol keys (prefer `InjectionKey<T>`) for `provide/inject` in plugins
19- Add a small typed composable wrapper for required injections to fail fast
20 
21## Structure Plugins for `app.use()`
22 
23A Vue plugin must be either:
24- An object with `install(app, options?)`
25- A function with the same signature
26 
27**BAD:**
28```ts
29const notAPlugin = {
30  doSomething() {}
31}
32 
33app.use(notAPlugin)
34```
35 
36**GOOD:**
37```ts
38import type { App } from 'vue'
39 
40interface PluginOptions {
41  prefix?: string
42  debug?: boolean
43}
44 
45const myPlugin = {
46  install(app: App, options: PluginOptions = {}) {
47    const { prefix = 'my', debug = false } = options
48 
49    if (debug) {
50      console.log('Installing myPlugin with prefix:', prefix)
51    }
52 
53    app.provide('myPlugin', { prefix })
54  }
55}
56 
57app.use(myPlugin, { prefix: 'custom', debug: true })
58```
59 
60**GOOD:**
61```ts
62import type { App } from 'vue'
63 
64function simplePlugin(app: App, options?: { message: string }) {
65  app.config.globalProperties.$greet = () => options?.message ?? 'Hello!'
66}
67 
68app.use(simplePlugin, { message: 'Welcome!' })
69```
70 
71## Register Capabilities Explicitly in `install()`
72 
73Inside `install()`, wire behavior through Vue application APIs:
74- `app.component()` for global components
75- `app.directive()` for global directives
76- `app.provide()` for injectable services and config
77- `app.config.globalProperties` for optional global helpers (sparingly)
78 
79**BAD:**
80```ts
81const uselessPlugin = {
82  install(app, options) {
83    const service = createService(options)
84  }
85}
86```
87 
88**GOOD:**
89```ts
90const usefulPlugin = {
91  install(app, options) {
92    const service = createService(options)
93    app.provide(serviceKey, service)
94  }
95}
96```
97 
98## Type Plugin Contracts
99 
100Use Vue's `Plugin` type to keep install signatures and options type-safe.
101 
102```ts
103import type { App, Plugin } from 'vue'
104 
105interface MyOptions {
106  apiKey: string
107}
108 
109const myPlugin: Plugin<[MyOptions]> = {
110  install(app: App, options: MyOptions) {
111    app.provide(apiKeyKey, options.apiKey)
112  }
113}
114```
115 
116## Use Symbol Injection Keys in Plugins
117 
118String keys can collide (`'http'`, `'config'`, `'i18n'`). Use symbol keys with `InjectionKey<T>` so injections are unique and typed.
119 
120**BAD:**
121```ts
122export default {
123  install(app) {
124    app.provide('http', axios)
125    app.provide('config', appConfig)
126  }
127}
128```
129 
130**GOOD:**
131```ts
132import type { InjectionKey } from 'vue'
133import type { AxiosInstance } from 'axios'
134 
135interface AppConfig {
136  apiUrl: string
137  timeout: number
138}
139 
140export const httpKey: InjectionKey<AxiosInstance> = Symbol('http')
141export const configKey: InjectionKey<AppConfig> = Symbol('appConfig')
142 
143export default {
144  install(app) {
145    app.provide(httpKey, axios)
146    app.provide(configKey, { apiUrl: '/api', timeout: 5000 })
147  }
148}
149```
150 
151## Provide Required Injection Helpers
152 
153Wrap required injections in composables that throw clear setup errors.
154 
155```ts
156import { inject } from 'vue'
157import { authKey, type AuthService } from '@/injection-keys'
158 
159export function useAuth(): AuthService {
160  const auth = inject(authKey)
161  if (!auth) {
162    throw new Error('Auth plugin not installed. Did you forget app.use(authPlugin)?')
163  }
164  return auth
165}
166```
167