feat: generate components.d.ts for global components

Author: antfu

README.md

@@ -49,7 +49,7 @@ Use components in templates as you would usually do but NO `import` and `compone
 
 Basically, it will automatically turn this
 
-```vue
+```html
 <template>
   <div>
     <HelloWorld msg="Hello Vue 3.0 + Vite" />
@@ -65,7 +65,7 @@ export default {
 
 into this
 
-```vue
+```html
 <template>
   <div>
     <HelloWorld msg="Hello Vue 3.0 + Vite" />
@@ -84,6 +84,24 @@ export default {
 </script>
 ```
 
+## TypeScript
+
+To have TypeScript support for auto-imported components, there is [a PR](https://github.com/vuejs/vue-next/pull/3399) to Vue 3 extending the interface of global components. Currently, [Volar](https://github.com/johnsoncodehk/volar) has supported this usage already, if you are using Volar, you can change the config as following to get the support.
+
+```ts
+// vite.config.js
+import ViteComponents from 'vite-plugin-components'
+
+export default {
+  plugins: [
+    /* ... */
+    ViteComponents({
+      globalComponentsDeclaration: true,
+    }),
+  ],
+}
+```
+
 ## Vue 2 Support
 
 It just works.

examples/vue3/components.d.ts

@@ -0,0 +1,21 @@
+// generated by vite-plugin-components
+// read more https://github.com/vuejs/vue-next/pull/3399
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    CarbonSvg: typeof import('./src/components/CarbonSvg.svg')
+    ComponentA: typeof import('./src/components/ComponentA.vue')
+    ComponentB: typeof import('./src/components/ComponentB.vue')
+    ComponentD: typeof import('./src/components/ComponentD.vue')
+    MarkdownA: typeof import('./src/components/MarkdownA.md')
+    MarkdownB: typeof import('./src/components/MarkdownB.md')
+    Recursive: typeof import('./src/components/Recursive.vue')
+    ComponentC: typeof import('./src/components/component-c.vue')
+    Book: typeof import('./src/components/book/index.vue')
+    Avatar: typeof import('./src/components/global/avatar.vue')
+    UiButton: typeof import('./src/components/ui/button.vue')
+    UiNestedCheckbox: typeof import('./src/components/ui/nested/checkbox.vue')
+  }
+}
+
+export { }

examples/vue3/vite.config.ts

@@ -7,8 +7,10 @@ import Markdown from 'vite-plugin-md'
 import SVG from 'vite-plugin-vue-svg'
 
 const config: UserConfig = {
-  alias: {
-    '/~/': `${path.resolve(__dirname, 'src')}/`,
+  resolve: {
+    alias: {
+      '/~/': `${path.resolve(__dirname, 'src')}/`,
+    },
   },
   plugins: [
     Vue({
@@ -19,6 +21,7 @@ const config: UserConfig = {
     ViteComponents({
       extensions: ['vue', 'md', 'svg'],
       directoryAsNamespace: true,
+      globalComponentsDeclaration: true,
       globalNamespaces: ['global'],
       importPathTransform: path => path.endsWith('.svg') ? `${path}?component` : undefined,
       customLoaderMatcher: path => path.endsWith('.md'),

src/declaration.ts

@@ -0,0 +1,29 @@
+import { resolve, dirname, relative } from 'path'
+import fs from 'fs/promises'
+import { Context } from './context'
+
+export async function generateDeclaration(ctx: Context, root: string, filepath: string) {
+  const lines = Object.values(ctx.componentNameMap)
+    .map(({ path, name, importName }) => {
+      const related = path.startsWith('/')
+        ? `./${relative(dirname(filepath), resolve(root, path.slice(1)))}`
+        : path
+      let entry = `${name}: typeof import('${related}')`
+      if (importName)
+        entry += `['${importName}']`
+      return entry
+    })
+
+  const code = `// generated by vite-plugin-components
+// read more https://github.com/vuejs/vue-next/pull/3399
+
+declare module 'vue' {
+  export interface GlobalComponents {
+    ${lines.join('\n    ')}
+  }
+}
+
+export { }
+`
+  await fs.writeFile(filepath, code, 'utf-8')
+}

src/index.ts

@@ -1,9 +1,12 @@
+import { resolve } from 'path'
+import fs from 'fs/promises'
 import type { Plugin } from 'vite'
 import { Options, Transformer } from './types'
 import { Context } from './context'
 import { parseId } from './utils'
 import { Vue3Transformer } from './transforms/vue3'
 import { Vue2Transformer } from './transforms/vue2'
+import { generateDeclaration } from './declaration'
 
 function VitePluginComponents(options: Options = {}): Plugin {
   let ctx: Context
@@ -20,6 +23,12 @@ function VitePluginComponents(options: Options = {}): Plugin {
       transformer = ctx.options.transformer === 'vue2'
         ? Vue2Transformer(ctx)
         : Vue3Transformer(ctx)
+
+      if (options.globalComponentsDeclaration) {
+        ctx.searchGlob()
+        const path = resolve(config.root, typeof options.globalComponentsDeclaration === 'string' ? options.globalComponentsDeclaration : 'components.d.ts')
+        generateDeclaration(ctx, config.root, path)
+      }
     },
     configureServer(server) {
       ctx.setServer(server)

src/types.ts

@@ -89,6 +89,17 @@ export interface Options {
    * @default 'vue3'
    */
   transformer?: 'vue3' | 'vue2'
+
+  /**
+   * Generate TypeScript declaration for global components
+   *
+   * Accept boolean or a path related to project root
+   *
+   * @see https://github.com/vuejs/vue-next/pull/3399
+   * @see https://github.com/johnsoncodehk/volar#using
+   * @default false
+   */
+  globalComponentsDeclaration?: boolean | string
 }
 
 export type ResolvedOptions = Omit<