feat(runtime-core): add ComponentCustomProperties interface

packages/runtime-core/src/componentProxy.ts

@@ -24,6 +24,34 @@ import {
 } from './componentRenderUtils'
 import { warn } from './warning'
 
+//
+/**
+ * Custom properties added to component instances in any way and can be accessed through `this`
+ *
+ * @example
+ * Here is an example of adding a property `$router` to every component instance:
+ * ```ts
+ * import { createApp } from 'vue'
+ * import { Router, createRouter } from 'vue-router'
+ *
+ * declare module '@vue/runtime-core' {
+ *   interface ComponentCustomProperties {
+ *     $router: Router
+ *   }
+ * }
+ *
+ * // effectively adding the router to every component instance
+ * const app = createApp({})
+ * const router = createRouter()
+ * app.config.globalProperties.$router = router
+ *
+ * const vm = app.mount('#app')
+ * // we cann access the router from the instance
+ * vm.$router.push('/')
+ * ```
+ */
+export interface ComponentCustomProperties {}
+
 // public properties exposed on the proxy, which is used as the render context
 // in templates (as `this` in the render option)
 export type ComponentPublicInstance<
@@ -53,7 +81,8 @@ export type ComponentPublicInstance<
   UnwrapRef<B> &
   D &
   ExtractComputedReturns<C> &
-  M
+  M &
+  ComponentCustomProperties
 
 const publicPropertiesMap: Record<
   string,

packages/runtime-core/src/index.ts

@@ -192,7 +192,10 @@ export {
   ComponentOptionsWithObjectProps as ComponentOptionsWithProps,
   ComponentOptionsWithArrayProps
 } from './componentOptions'
-export { ComponentPublicInstance } from './componentProxy'
+export {
+  ComponentPublicInstance,
+  ComponentCustomProperties
+} from './componentProxy'
 export {
   Renderer,
   RendererNode,

test-dts/componentCustomProperties.test-d.ts

@@ -0,0 +1,20 @@
+import { expectError } from 'tsd'
+import { defineComponent } from './index'
+
+declare module '@vue/runtime-core' {
+  interface ComponentCustomProperties {
+    state: 'stopped' | 'running'
+  }
+}
+
+export const Custom = defineComponent({
+  data: () => ({ counter: 0 }),
+  methods: {
+    aMethod() {
+      expectError(this.notExisting)
+      this.counter++
+      this.state = 'running'
+      expectError((this.state = 'not valid'))
+    }
+  }
+})