Proper TypeScript Type Augmentation for Plugins

Rule

When creating Vue plugins that add global properties, you MUST properly augment TypeScript types. The augmentation file MUST contain at least one top-level import or export statement to be treated as a module.

Why This Matters

1. Without module syntax, types are overwritten: If your augmentation file isn't a module, it will OVERWRITE Vue's types instead of augmenting them, breaking type checking for the entire application.

1. Type safety: Proper augmentation enables autocomplete and type checking for plugin-provided properties.

1. IDE support: Developers get proper IntelliSense for global properties like this.$translate.

1. Error prevention: Catch typos and incorrect usage at compile time rather than runtime.

Critical Rule: Module Syntax Required

// BAD - This OVERWRITES Vue types instead of augmenting!
// types/vue.d.ts
declare module 'vue' {
  interface ComponentCustomProperties {
    $translate: (key: string) => string
  }
}

// GOOD - The export {} makes this a module, so it AUGMENTS types
// types/vue.d.ts
export {}  // This line is CRITICAL!

declare module 'vue' {
  interface ComponentCustomProperties {
    $translate: (key: string) => string
  }
}

Complete Plugin Type Augmentation Example

// plugins/i18n.ts
import type { App, InjectionKey } from 'vue'

export interface I18nOptions {
  locale: string
  messages: Record<string, Record<string, string>>
}

export interface I18nInstance {
  translate: (key: string) => string
  locale: string
}

export const i18nInjectionKey: InjectionKey<I18nInstance> = Symbol('i18n')

export function createI18n(options: I18nOptions) {
  const i18n: I18nInstance = {
    translate(key: string) {
      return options.messages[options.locale]?.[key] ?? key
    },
    locale: options.locale
  }

  return {
    install(app: App) {
      // For Composition API
      app.provide(i18nInjectionKey, i18n)

      // For Options API / templates
      app.config.globalProperties.$t = i18n.translate
      app.config.globalProperties.$i18n = i18n
    }
  }
}

// types/i18n.d.ts (or in the same file after export)
export {}

declare module 'vue' {
  interface ComponentCustomProperties {
    $t: (key: string) => string
    $i18n: I18nInstance
  }
}

Alternative: Augment @vue/runtime-core

Some plugins augment @vue/runtime-core instead of vue:

// types/global.d.ts
export {}

declare module '@vue/runtime-core' {
  interface ComponentCustomProperties {
    $myPlugin: MyPluginInstance
  }
}

Both approaches work, but 'vue' is more common in application code.

Ensure tsconfig.json Includes the Declaration File

{
  "compilerOptions": {
    // ...
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.vue",
    "types/**/*.d.ts"  // Include your declaration files
  ]
}

For Library Authors: package.json Types Field

If publishing a plugin as a package:

{
  "name": "my-vue-plugin",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/types/index.d.ts",
      "import": "./dist/index.mjs"
    }
  }
}

Common Errors and Solutions

Error: Property '$xyz' does not exist on type

1. Check that your .d.ts file has export {} or an import statement
2. Verify the file is included in tsconfig.json
3. Restart your TypeScript language server (VS Code: Cmd+Shift+P > "Restart TS Server")

Error: Types work in some components but not others

This often happens when using Vetur instead of Volar. If you're on Vue 3, switch to Volar (Vue - Official extension).

Error in Options API but not Composition API

Global properties on this require proper augmentation of ComponentCustomProperties. The Composition API uses inject() which is typed separately.

References

• Vue.js TypeScript with Options API
• TypeScript Module Augmentation
• Vue.js Plugins Documentation