1# Prefer provide/inject Over Global Properties in Plugins
2 
3## Rule
4 
5When creating Vue plugins, prefer using `app.provide()` to make plugin functionality available to components instead of attaching properties to `app.config.globalProperties`.
6 
7## Why This Matters
8 
91. **globalProperties don't work in setup()**: Properties attached to `globalProperties` are only accessible via `this` in Options API. They are NOT available in the Composition API's `setup()` function.
10 
112. **Type safety**: `provide/inject` integrates better with TypeScript and requires less type augmentation boilerplate.
12 
133. **Testability**: Injected dependencies are easier to mock in tests compared to global properties.
14 
154. **Code clarity**: Explicit `inject()` calls make dependencies visible, while global properties can appear "magic".
16 
175. **Scoping**: `provide/inject` follows Vue's component hierarchy, making it easier to provide different values to different parts of your app.
18 
19## Bad Practice
20 
21```typescript
22// plugins/i18n.ts
23export default {
24  install(app, options) {
25    // Attaching to globalProperties - only works with Options API
26    app.config.globalProperties.$translate = (key: string) => {
27      return key.split('.').reduce((o, i) => o?.[i], options)
28    }
29  }
30}
31 
32// In component - requires type augmentation for TypeScript
33// Also DOES NOT work in <script setup>
34export default {
35  mounted() {
36    console.log(this.$translate('greeting.hello'))
37  }
38}
39```
40 
41## Good Practice
42 
43```typescript
44// plugins/i18n.ts
45import type { InjectionKey, App } from 'vue'
46 
47export interface I18nOptions {
48  [key: string]: string | I18nOptions
49}
50 
51export interface I18n {
52  translate: (key: string) => string
53  options: I18nOptions
54}
55 
56export const i18nKey: InjectionKey<I18n> = Symbol('i18n')
57 
58export default {
59  install(app: App, options: I18nOptions) {
60    const translate = (key: string): string => {
61      return key.split('.').reduce((o, i) => o?.[i], options) as string ?? key
62    }
63 
64    // Use provide for Composition API compatibility
65    app.provide(i18nKey, { translate, options })
66  }
67}
68 
69// In component - works in setup() and has full type safety
70<script setup lang="ts">
71import { inject } from 'vue'
72import { i18nKey } from '@/plugins/i18n'
73 
74const i18n = inject(i18nKey)
75console.log(i18n?.translate('greeting.hello'))
76</script>
77```
78 
79## Hybrid Approach
80 
81If you must support both APIs (e.g., for backwards compatibility), provide both:
82 
83```typescript
84export default {
85  install(app: App, options: I18nOptions) {
86    const i18n = {
87      translate: (key: string) => /* ... */
88    }
89 
90    // For Composition API
91    app.provide(i18nKey, i18n)
92 
93    // For Options API (use sparingly)
94    app.config.globalProperties.$i18n = i18n
95  }
96}
97```
98 
99## TypeScript Type Augmentation (if using globalProperties)
100 
101If you must use globalProperties, you need proper type augmentation:
102 
103```typescript
104// types/vue.d.ts
105export {}
106 
107declare module 'vue' {
108  interface ComponentCustomProperties {
109    $translate: (key: string) => string
110  }
111}
112```
113 
114**Important**: The file MUST contain `export {}` or another top-level export/import. Without it, the augmentation will OVERWRITE types instead of augmenting them.
115 
116## References
117 
118- [Vue.js Plugins Documentation](https://vuejs.org/guide/reusability/plugins.html)
119- [Vue.js Provide/Inject](https://vuejs.org/guide/components/provide-inject.html)
120- [TypeScript with Options API](https://vuejs.org/guide/typescript/options-api.html)
121