feat!: add build option for tsc -b

sxzz · sxzz · commit 1314644bf81e · 2025-08-04T02:18:24.000+08:00
diff --git a/README.md b/README.md
@@ -91,11 +91,19 @@ Resolve external types used in `.d.ts` files from `node_modules`.
 > [!NOTE]
 > These options are only applicable when `oxc` and `tsgo` are not enabled.
 
+#### `build`
+
+Build mode for the TypeScript compiler:
+
+- If `true`, the plugin will use [`tsc -b`](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript) to build the project and all referenced projects before emitting `.d.ts` files.
+- If `false`, the plugin will use [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) to emit `.d.ts` files without building referenced projects.
+
+**Default:** `false`
+
 #### `incremental`
 
 Controls how project references and incremental builds are handled:
 
-- If your `tsconfig.json` uses [`references`](https://www.typescriptlang.org/tsconfig/#references), the plugin will use [`tsc -b`](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript) to build the project and all referenced projects before emitting `.d.ts` files.
 - If `incremental` is `true`, all built files (including [`.tsbuildinfo`](https://www.typescriptlang.org/tsconfig/#tsBuildInfoFile)) will be written to disk, similar to running `tsc -b` in your project.
 - If `incremental` is `false`, built files are kept in memory, minimizing disk usage.
 
diff --git a/src/generate.ts b/src/generate.ts
@@ -50,6 +50,7 @@ export type DtsMap = Map<string, TsModule>
 export function createGeneratePlugin({
   tsconfig,
   tsconfigRaw,
+  build,
   incremental,
   cwd,
   oxc,
@@ -65,6 +66,7 @@ export function createGeneratePlugin({
   | 'cwd'
   | 'tsconfig'
   | 'tsconfigRaw'
+  | 'build'
   | 'incremental'
   | 'oxc'
   | 'emitDtsOnly'
@@ -248,6 +250,7 @@ export function createGeneratePlugin({
           const options: Omit<TscOptions, 'programs'> = {
             tsconfig,
             tsconfigRaw,
+            build,
             incremental,
             cwd,
             entries,
diff --git a/src/options.ts b/src/options.ts
@@ -8,7 +8,8 @@ import {
 } from 'get-tsconfig'
 import type { IsolatedDeclarationsOptions } from 'rolldown/experimental'
 
-export interface Options {
+//#region General Options
+export interface GeneralOptions {
   /**
    * The directory in which the plugin will search for the `tsconfig.json` file.
    */
@@ -45,6 +46,36 @@ export interface Options {
    */
   tsconfigRaw?: Omit<TsConfigJson, 'compilerOptions'>
 
+  /**
+   * Override the `compilerOptions` specified in `tsconfig.json`.
+   *
+   * @see https://www.typescriptlang.org/tsconfig/#compilerOptions
+   */
+  compilerOptions?: TsConfigJson.CompilerOptions
+
+  /**
+   * If `true`, the plugin will generate declaration maps (`.d.ts.map`) for `.d.ts` files.
+   */
+  sourcemap?: boolean
+
+  /**
+   * Resolve external types used in `.d.ts` files from `node_modules`.
+   */
+  resolve?: boolean | (string | RegExp)[]
+}
+
+//#region tsc Options
+export interface TscOptions {
+  /**
+   * Build mode for the TypeScript compiler:
+   *
+   * - If `true`, the plugin will use [`tsc -b`](https://www.typescriptlang.org/docs/handbook/project-references.html#build-mode-for-typescript) to build the project and all referenced projects before emitting `.d.ts` files.
+   * - If `false`, the plugin will use [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html) to emit `.d.ts` files without building referenced projects.
+   *
+   * @default false
+   */
+  build?: boolean
+
   /**
    * If your tsconfig.json has
    * [`references`](https://www.typescriptlang.org/tsconfig/#references) option,
@@ -76,31 +107,6 @@ export interface Options {
    */
   incremental?: boolean
 
-  /**
-   * Override the `compilerOptions` specified in `tsconfig.json`.
-   *
-   * @see https://www.typescriptlang.org/tsconfig/#compilerOptions
-   */
-  compilerOptions?: TsConfigJson.CompilerOptions
-
-  /**
-   * If `true`, the plugin will generate `.d.ts` files using Oxc,
-   * which is significantly faster than the TypeScript compiler.
-   *
-   * This option is automatically enabled when `isolatedDeclarations` in `compilerOptions` is set to `true`.
-   */
-  oxc?: boolean | Omit<IsolatedDeclarationsOptions, 'sourcemap'>
-
-  /**
-   * If `true`, the plugin will generate declaration maps (`.d.ts.map`) for `.d.ts` files.
-   */
-  sourcemap?: boolean
-
-  /**
-   * Resolve external types used in `.d.ts` files from `node_modules`.
-   */
-  resolve?: boolean | (string | RegExp)[]
-
   /**
    * If `true`, the plugin will generate `.d.ts` files using `vue-tsc`.
    */
@@ -119,16 +125,6 @@ export interface Options {
    */
   eager?: boolean
 
-  /**
-   * **[Experimental]** Enables DTS generation using `tsgo`.
-   *
-   * To use this option, make sure `@typescript/native-preview` is installed as a dependency.
-   *
-   * **Note:** This option is not yet recommended for production environments.
-   * `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.
@@ -152,6 +148,30 @@ export interface Options {
   emitJs?: boolean
 }
 
+export interface Options extends GeneralOptions, TscOptions {
+  //#region Oxc
+
+  /**
+   * If `true`, the plugin will generate `.d.ts` files using Oxc,
+   * which is significantly faster than the TypeScript compiler.
+   *
+   * This option is automatically enabled when `isolatedDeclarations` in `compilerOptions` is set to `true`.
+   */
+  oxc?: boolean | Omit<IsolatedDeclarationsOptions, 'sourcemap'>
+
+  //#region TypeScript Go
+
+  /**
+   * **[Experimental]** Enables DTS generation using `tsgo`.
+   *
+   * To use this option, make sure `@typescript/native-preview` is installed as a dependency.
+   *
+   * **Note:** This option is not yet recommended for production environments.
+   * `tsconfigRaw` and `isolatedDeclarations` options will be ignored when this option is enabled.
+   */
+  tsgo?: boolean
+}
+
 type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U
 
 export type OptionsResolved = Overwrite<
@@ -167,21 +187,25 @@ let warnedTsgo = false
 
 export function resolveOptions({
   cwd = process.cwd(),
+  dtsInput = false,
+  emitDtsOnly = false,
   tsconfig,
-  incremental = false,
-  compilerOptions = {},
   tsconfigRaw: overriddenTsconfigRaw = {},
-  oxc,
+  compilerOptions = {},
   sourcemap,
-  dtsInput = false,
-  emitDtsOnly = false,
   resolve = false,
+
+  // tsc
+  build = false,
+  incremental = false,
   vue = false,
   parallel = false,
   eager = false,
-  tsgo = false,
   newContext = false,
   emitJs,
+
+  oxc,
+  tsgo = false,
 }: Options): OptionsResolved {
   let resolvedTsconfig: TsConfigJsonResolved | undefined
   if (tsconfig === true || tsconfig == null) {
@@ -250,19 +274,23 @@ export function resolveOptions({
 
   return {
     cwd,
+    dtsInput,
+    emitDtsOnly,
     tsconfig,
     tsconfigRaw,
-    incremental,
-    oxc,
     sourcemap,
-    dtsInput,
-    emitDtsOnly,
     resolve,
+
+    // tsc
+    build,
+    incremental,
     vue,
     parallel,
     eager,
-    tsgo,
     newContext,
     emitJs,
+
+    oxc,
+    tsgo,
   }
 }
diff --git a/src/tsc/index.ts b/src/tsc/index.ts
@@ -16,6 +16,7 @@ export interface TscOptions {
   tsconfig?: string
   tsconfigRaw: TsConfigJson
   cwd: string
+  build: boolean
   incremental: boolean
   entries?: string[]
   id: string
@@ -174,6 +175,7 @@ function createTsProgram({
   id,
   tsconfig,
   tsconfigRaw,
+  build,
   incremental,
   vue,
   cwd,
@@ -188,7 +190,7 @@ function createTsProgram({
   )
 
   // If the tsconfig has project references, build the project tree.
-  if (tsconfig && parsedConfig.projectReferences?.length) {
+  if (tsconfig && build) {
     // Build the project tree and collect all projects.
     const projectPaths = buildSolution(tsconfig, incremental, context)
     debug(`collected projects: ${JSON.stringify(projectPaths)}`)
