feat!: reuse generated dts by default

sxzz · sxzz · commit 9ea4b95877d3 · 2025-07-19T06:02:30.000+08:00
diff --git a/README.md b/README.md
@@ -148,6 +148,17 @@ This is especially useful when you have a single `tsconfig.json` for multiple pr
 
 ---
 
+### newContext
+
+If `true`, the plugin will create a new isolated context for each build,
+ensuring that previously generated `.d.ts` code and caches are not reused.
+
+By default, the plugin may reuse internal caches or incremental build artifacts
+to speed up repeated builds. Enabling this option forces a clean context,
+guaranteeing that all type definitions are generated from scratch.
+
+---
+
 ### tsgo
 
 **[Experimental]** Enables DTS generation using [`tsgo`](https://github.com/microsoft/typescript-go).
diff --git a/src/generate.ts b/src/generate.ts
@@ -52,6 +52,7 @@ export function createGeneratePlugin({
   parallel,
   eager,
   tsgo,
+  newContext,
 }: Pick<
   OptionsResolved,
   | 'cwd'
@@ -64,6 +65,7 @@ export function createGeneratePlugin({
   | 'parallel'
   | 'eager'
   | 'tsgo'
+  | 'newContext'
 >): Plugin {
   const dtsMap: DtsMap = new Map<string, TsModule>()
 
@@ -105,7 +107,9 @@ export function createGeneratePlugin({
         tsgoDist = await runTsgo(cwd, tsconfig)
       } else if (!parallel && (!isolatedDeclarations || vue)) {
         tscModule = await import('./tsc/index.ts')
-        tscContext = eager ? undefined : tscModule.createContext()
+        if (newContext) {
+          tscContext = tscModule.createContext()
+        }
       }
 
       if (!Array.isArray(options.input)) {
@@ -279,7 +283,10 @@ export function createGeneratePlugin({
       if (!debug.enabled && tsgoDist) {
         await rm(tsgoDist, { recursive: true, force: true }).catch(() => {})
       }
-      tscContext = tsgoDist = undefined
+      tsgoDist = undefined
+      if (newContext) {
+        tscContext = undefined
+      }
     },
   }
 }
diff --git a/src/index.ts b/src/index.ts
@@ -5,6 +5,7 @@ import { createFakeJsPlugin } from './fake-js.ts'
 import { createGeneratePlugin } from './generate.ts'
 import { resolveOptions, type Options } from './options.ts'
 import { createDtsResolvePlugin } from './resolver.ts'
+import { createContext, type TscContext } from './tsc/index.ts'
 import type { Plugin } from 'rolldown'
 
 export {
@@ -35,8 +36,10 @@ export function dts(options: Options = {}): Plugin[] {
 }
 
 export {
+  createContext,
   createFakeJsPlugin,
   createGeneratePlugin,
   resolveOptions,
   type Options,
+  type TscContext,
 }
diff --git a/src/options.ts b/src/options.ts
@@ -130,6 +130,18 @@ export interface Options {
    * `tsconfigRaw` and `isolatedDeclarations` options will be ignored when this option is enabled.
    */
   tsgo?: boolean
+
+  /**
+   * If `true`, the plugin will create a new isolated context for each build,
+   * ensuring that previously generated `.d.ts` code and caches are not reused.
+   *
+   * By default, the plugin may reuse internal caches or incremental build artifacts
+   * to speed up repeated builds. Enabling this option forces a clean context,
+   * guaranteeing that all type definitions are generated from scratch.
+   *
+   * **Default:** `false`
+   */
+  newContext?: boolean
 }
 
 type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U
@@ -160,6 +172,7 @@ export function resolveOptions({
   parallel = false,
   eager = false,
   tsgo = false,
+  newContext = false,
 }: Options): OptionsResolved {
   let resolvedTsconfig: TsConfigJsonResolved | undefined
   if (tsconfig === true || tsconfig == null) {
@@ -222,5 +235,6 @@ export function resolveOptions({
     parallel,
     eager,
     tsgo,
+    newContext,
   }
 }
