feat: introduce syncMode to control the behavior of generating files (#882)

Author: kevinmarrec

README.md

@@ -465,6 +465,17 @@ Components({
  types: [
  /* ... */
  ],
+
+ // Save component information into a JSON file for other tools to consume.
+ // Provide a filepath to save the JSON file.
+ // When set to `true`, it will save to `./.components-info.json`
+ dumpComponentsInfo: false,
+
+ // The mode for syncing the components.d.ts and .components-info.json file.
+ // 'append': only append the new components to the existing files.
+ // 'overwrite': overwrite the whole existing files with the current components.
+ // 'default': use 'append' strategy when using dev server, 'overwrite' strategy when using build.
+ syncMode: 'default',
 })
 ```
 

src/core/context.ts

@@ -29,6 +29,7 @@ export class Context {
  private _componentUsageMap: Record<string, Set<string>> = {}
  private _componentCustomMap: Record<string, ComponentInfo> = {}
  private _directiveCustomMap: Record<string, ComponentInfo> = {}
+ private _removeUnused = false
  private _server: ViteDevServer | undefined
 
  root = process.cwd()
@@ -42,6 +43,7 @@ export class Context {
  this.options = resolveOptions(rawOptions, this.root)
  this.sourcemap = rawOptions.sourcemap ?? true
  this.generateDeclaration = throttle(500, this._generateDeclaration.bind(this), { noLeading: false })
+ this._removeUnused = this.options.syncMode === 'overwrite'
 
  if (this.options.dumpComponentsInfo) {
  const dumpComponentsInfo = this.options.dumpComponentsInfo === true
@@ -78,6 +80,7 @@ export class Context {
  return
 
  this._server = server
+ this._removeUnused = this.options.syncMode !== 'append'
  this.setupWatcher(server.watcher)
  }
 
@@ -299,27 +302,27 @@ export class Context {
  this._searched = true
  }
 
- _generateDeclaration(removeUnused = !this._server) {
+ _generateDeclaration(removeUnused = this._removeUnused) {
  if (!this.options.dts)
  return
 
  debug.declaration('generating dts')
  return writeDeclaration(this, this.options.dts, removeUnused)
  }
 
- generateDeclaration(removeUnused = !this._server): void {
+ generateDeclaration(removeUnused = this._removeUnused): void {
  this._generateDeclaration(removeUnused)
  }
 
- _generateComponentsJson(removeUnused = !this._server) {
+ _generateComponentsJson(removeUnused = this._removeUnused) {
  if (!Object.keys(this._componentNameMap).length)
  return
 
  debug.components('generating components-info')
  return writeComponentsJson(this, removeUnused)
  }
 
- generateComponentsJson(removeUnused = !this._server): void {
+ generateComponentsJson(removeUnused = this._removeUnused): void {
  this._generateComponentsJson(removeUnused)
  }
 

src/core/options.ts

@@ -25,6 +25,7 @@ export const defaultOptions: Omit<Required<Options>, 'include' | 'exclude' | 'ex
 
  sourcemap: true,
  dumpComponentsInfo: false,
+ syncMode: 'default',
  prefix: '',
 }
 

src/types.ts

@@ -220,6 +220,16 @@ export interface Options {
  * @default false
  */
  dumpComponentsInfo?: boolean | string
+
+ /**
+ * The mode for syncing the components.d.ts and .components-info.json file.
+ * - `append`: only append the new components to the existing files.
+ * - `overwrite`: overwrite the whole existing files with the current components.
+ * - `default`: use `append` strategy when using dev server, `overwrite` strategy when using build.
+ *
+ * @default 'default'
+ */
+ syncMode?: 'default' | 'append' | 'overwrite'
 }
 
 export type ResolvedOptions = Omit<

test/__snapshots__/dts.test.ts.snap

@@ -150,7 +150,7 @@ declare module 'vue' {
 "
 `;
 
-exports[`dts > writeDeclaration - keep unused 1`] = `
+exports[`dts > writeDeclaration - append 1`] = `
 "/* eslint-disable */
 // @ts-nocheck
 // Generated by unplugin-vue-components
@@ -175,6 +175,28 @@ declare module 'vue' {
 "
 `;
 
+exports[`dts > writeDeclaration - overwrite 1`] = `
+"/* eslint-disable */
+// @ts-nocheck
+// Generated by unplugin-vue-components
+// Read more: https://github.com/vuejs/core/pull/3399
+// biome-ignore lint: disable
+export {}
+
+/* prettier-ignore */
+declare module 'vue' {
+ export interface GlobalComponents {
+ RouterLink: typeof import('vue-router')['RouterLink']
+ RouterView: typeof import('vue-router')['RouterView']
+ TestComp: typeof import('test/component/TestComp')['default']
+ }
+ export interface GlobalDirectives {
+ vLoading: typeof import('test/directive/Loading')['default']
+ }
+}
+"
+`;
+
 exports[`dts > writeDeclaration 1`] = `
 "/* eslint-disable */
 // @ts-nocheck

test/dts.test.ts

@@ -48,8 +48,8 @@ const _directive_loading = _resolveDirective("loading")`
  expect(await readFile(filepath, 'utf-8')).matchSnapshot()
  })
 
- it('writeDeclaration - keep unused', async () => {
- const filepath = path.resolve(__dirname, 'tmp/dts-keep-unused.d.ts')
+ it.each(['append', 'overwrite'] as const)('writeDeclaration - %s', async (syncMode) => {
+ const filepath = path.resolve(__dirname, 'tmp/dts-test-sync-mode.d.ts')
  await writeFile(
  filepath,
  `
@@ -70,18 +70,16 @@ declare module 'vue' {
  resolvers: resolver,
  directives: true,
  dts: filepath,
+ syncMode,
  })
  const code = `
 const _component_test_comp = _resolveComponent("test-comp")
 const _directive_loading = _resolveDirective("loading")`
  await ctx.transform(code, '')
- await ctx._generateDeclaration(false)
+ await ctx._generateDeclaration()
 
  const contents = await readFile(filepath, 'utf-8')
  expect(contents).matchSnapshot()
- expect(contents).not.toContain('OldComp')
- expect(contents).not.toContain('comment')
- expect(contents).toContain('vSome')
  })
 
  it('components only', async () => {