@d1g1tal/tsbuild 1.3.2 → 1.5.0

package/README.md

@@ -8,7 +8,7 @@
 [![Node.js](https://img.shields.io/node/v/@d1g1tal/tsbuild)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-A TypeScript build tool that combines three tools into one workflow: **TypeScript's type system** for correctness, **esbuild** for speed, and **SWC** for legacy decorator metadata (optional, not installed by default). Built for modern ESM-only projects on Node.js 20.16.0+.
+A TypeScript build tool that combines three tools into one workflow: **TypeScript's type system** for correctness, **esbuild** for speed, and **SWC** for legacy decorator metadata (optional, not installed by default). Built for modern ESM-only projects on Node.js 22+.
 
 TC39 standard decorators are supported natively — no additional dependencies needed. SWC is only required if you are still using `experimentalDecorators` with `emitDecoratorMetadata`.
 
@@ -42,38 +42,6 @@ The build runs in two phases:
 
 If `declaration` is not enabled, phase 2 is just the esbuild step.
 
-## Quick Start
-
-The only thing tsbuild requires in `tsconfig.json` is an `outDir`. Everything else carries over from your existing config:
-
-```jsonc
-{
-  "compilerOptions": {
-    "outDir": "./dist"
-    // ... your existing TypeScript config
-  },
-  "tsbuild": {} // entry points are inferred from package.json automatically
-}
-```
-
-Then, if tsbuild is installed globally:
-
-```bash
-tsbuild
-```
-
-Or if installed locally as a dev dependency, add a script to `package.json` and run it:
-
-```json
-{ "scripts": { "build": "tsbuild" } }
-```
-
-```bash
-pnpm build
-```
-
-That's it. tsbuild reads your `compilerOptions`, infers entry points from your `package.json`, and builds. See [Configuration Options](#configuration-options) for everything you can customise.
-
 ## Installation
 
 ### Global Installation (Recommended for CLI usage)
@@ -111,8 +79,109 @@ yarn add -D @d1g1tal/tsbuild
 
 ### Requirements
 
-- **Node.js**: >=20.16.0
-- **pnpm**: >=9.0.0
+- **Node.js**: >=22.0.0
+- **pnpm**: >=10.13.0 (if using corepack)
+
+## Quick Start
+
+The only thing tsbuild requires in `tsconfig.json` is an `outDir`. Everything else carries over from your existing config.
+
+### Minimal config — no `tsbuild` section needed
+
+```jsonc
+{
+  "compilerOptions": {
+    "outDir": "./dist"
+    // ... your existing TypeScript config
+  }
+}
+```
+
+Entry points are inferred from `package.json` automatically, and all dependencies are treated as external by default.
+
+### Bundle a specific package into the output
+
+By default, bare specifiers (e.g. `lodash-es`) are kept as external imports. Use `noExternal` to force a package to be inlined into the bundle:
+
+```jsonc
+{
+  "compilerOptions": {
+    "outDir": "./dist"
+    // ... your existing TypeScript config
+  },
+  "tsbuild": {
+    "noExternal": ["evicting-cache"]  // bundle evicting-cache into the output instead of leaving it as an import
+  }
+}
+```
+
+### Preferred `tsconfig.json` setup — incremental (recommended)
+
+`incremental` defaults to `true` in tsbuild unless you explicitly set it to `false` in your `tsconfig.json`. With incremental enabled, TypeScript only re-emits changed files on each build and the declaration cache is preserved across runs, making repeated builds significantly faster.
+
+```jsonc
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "incremental": true,           // redundant — tsbuild enables this by default, but explicit is clear
+    "isolatedDeclarations": true,  // recommended: enables faster parallel declaration emit
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "strict": true,
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler", // recommended for library builds processed by a bundler
+    // lib controls platform detection — omitting "DOM" targets Node.js (platform: "node").
+    // Add "DOM" to target the browser (platform: "browser").
+    "lib": ["ESNext"]             // Node.js library — no DOM APIs
+    // "lib": ["ESNext", "DOM"]   // Browser library — includes DOM APIs, sets platform to "browser"
+  }
+}
+```
+
+### Preferred `tsconfig.json` setup — non-incremental
+
+Set `incremental: false` to opt out of the `.tsbuildinfo` cache entirely. Every build is a full compilation from scratch. Useful for CI environments where you want deterministic, cache-free output.
+
+```jsonc
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true,
+    "incremental": false,          // disables TypeScript's .tsbuildinfo cache and tsbuild's DTS cache
+    "isolatedDeclarations": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "strict": true,
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler", // recommended for library builds processed by a bundler
+    // lib controls platform detection — omitting "DOM" targets Node.js (platform: "node").
+    // Add "DOM" to target the browser (platform: "browser").
+    "lib": ["ESNext"]             // Node.js library — no DOM APIs
+    // "lib": ["ESNext", "DOM"]   // Browser library — includes DOM APIs, sets platform to "browser"
+  }
+}
+```
+
+Then, if tsbuild is installed globally:
+
+```bash
+tsbuild
+```
+
+Or if installed locally as a dev dependency, add a script to `package.json` and run it:
+
+```json
+{ "scripts": { "build": "tsbuild" } }
+```
+
+```bash
+pnpm build
+```
+
+That's it. tsbuild reads your `compilerOptions`, infers entry points from your `package.json`, and builds. See [Configuration Options](#configuration-options) for everything you can customize.
 
 ## Usage
 
@@ -122,7 +191,7 @@ yarn add -D @d1g1tal/tsbuild
 
 Because tsbuild uses the TypeScript compiler API directly, it reads your `compilerOptions` automatically. There is no need to re-declare `target`, `module`, `lib`, `strict`, `paths`, `moduleResolution`, `baseUrl`, or any other TypeScript settings in a separate config — they are already in your `tsconfig.json`, and tsbuild honours them as-is.
 
-The `tsbuild` section only covers options that don't belong in `compilerOptions`: bundling behaviour, entry points, watch mode, output formatting, and similar build-specific settings.
+The `tsbuild` section only covers options that don't belong in `compilerOptions`: bundling behavior, entry points, watch mode, output formatting, and similar build-specific settings.
 
 This means your type-checker and your build always use the exact same TypeScript configuration — no drift, no duplication.
 
@@ -133,7 +202,7 @@ Declaration generation is **not required**. If `declaration: true` is already se
 
 Everything else carries over automatically.
 
-Add a `tsbuild` property to your `tsconfig.json` with only the options you need to customise:
+Add a `tsbuild` property to your `tsconfig.json` with only the options you need to customize:
 
 ```jsonc
 {
@@ -215,17 +284,17 @@ tsbuild uses two separate caches to speed up repeated builds, and two flags to c
 
 ### How it works
 
-Enable incremental compilation in `tsconfig.json`:
+Incremental compilation is **enabled by default** — no configuration needed. To opt out, explicitly set `incremental: false` in `tsconfig.json`:
 
 ```jsonc
 {
   "compilerOptions": {
-    "incremental": true
+    "incremental": false  // disables TypeScript's .tsbuildinfo cache and tsbuild's DTS cache
   }
 }
 ```
 
-With this set, each build maintains two caches inside a `.tsbuild/` directory:
+With incremental enabled, each build maintains two caches inside a `.tsbuild/` directory:
 
 | Cache | File | What it stores |
 |-------|------|----------------|
@@ -234,6 +303,20 @@ With this set, each build maintains two caches inside a `.tsbuild/` directory:
 
 On each build, TypeScript reads `.tsbuildinfo` to determine what changed and only re-emits those files. Changed `.d.ts` files overwrite their entries in the DTS cache; unchanged entries remain valid. If nothing changed, TypeScript skips emission entirely and the output phase is skipped too — this is why incremental rebuilds with no changes take ~5ms.
 
+### Ignoring the cache directory
+
+The `.tsbuild/` directory contains build artifacts that should not be committed to source control. Add it to your `.gitignore`:
+
+```bash
+echo '.tsbuild/' >> .gitignore
+```
+
+Or add the entry manually:
+
+```gitignore
+.tsbuild/
+```
+
 ### Flags
 
 **`--force` (`-f`)** — Runs the output phase (esbuild + DTS bundling) even when TypeScript detects no changes. Useful when something outside the source files changed (e.g. an environment variable or esbuild config) and you need to regenerate output without touching the caches.
@@ -441,7 +524,7 @@ When a circular dependency is detected between declaration files, tsbuild emits
 
 tsbuild is designed for speed:
 
-- **Incremental builds** - Only recompiles changed files
+- **Incremental builds** - Only recompile changed files
 - **In-memory declarations** - No intermediate disk I/O for `.d.ts` files
 - **Parallel processing** - Declaration bundling and transpilation run in parallel after type checking completes
 - **Smart caching** - Leverages `.tsbuildinfo` for TypeScript incremental compilation

package/dist/{QG4L36TP.js → 4BKT57QY.js}

@@ -29,7 +29,7 @@ import {
   toEsTarget,
   toJsxRenderingMode,
   typeMatcher
-} from "./7FPDHUPW.js";
+} from "./UYXU5EAU.js";
 
 // src/errors.ts
 import { SyntaxKind } from "typescript";
@@ -1933,6 +1933,13 @@ var IncrementalBuildCache = class {
   isBuildInfoFile(filePath) {
     return filePath === this.buildInfoPath;
   }
+  /**
+   * Checks if the cache is valid (not invalidated).
+   * @returns True if the cache is valid, false if it has been invalidated
+   */
+  isValid() {
+    return !this.invalidated;
+  }
   /**
    * Custom inspection tag for type.
    * @returns The string 'IncrementalBuildCache'
@@ -2091,7 +2098,7 @@ var _TypeScriptProject = class _TypeScriptProject {
     return Files.empty(this.buildConfiguration.outDir);
   }
   async build() {
-    Logger.header(`\u{1F680} tsbuild v${"1.3.2"}${this.configuration.compilerOptions.incremental ? " [incremental]" : ""}`);
+    Logger.header(`\u{1F680} tsbuild v${"1.5.0"}${this.configuration.compilerOptions.incremental && this.configuration.buildCache?.isValid() ? " [incremental]" : ""}`);
     try {
       const processes = [];
       const filesWereEmitted = await this.typeCheck();
@@ -2150,7 +2157,7 @@ var _TypeScriptProject = class _TypeScriptProject {
     }
     if (this.configuration.compilerOptions.emitDecoratorMetadata) {
       try {
-        const { swcDecoratorMetadataPlugin } = await import("./LEZQQWX3.js");
+        const { swcDecoratorMetadataPlugin } = await import("./RBRXNRTQ.js");
         plugins.push(swcDecoratorMetadataPlugin);
       } catch {
         throw new ConfigurationError("emitDecoratorMetadata is enabled but @swc/core is not installed. Install it with: pnpm add -D @swc/core");
@@ -2357,7 +2364,9 @@ var _TypeScriptProject = class _TypeScriptProject {
       compilerOptions: {
         ...{ outDir: defaultOutDirectory, noEmit: false, sourceMap: false, incremental: true, tsBuildInfoFile: Paths.join(cacheDirectory, buildInfoFile), lib: [] },
         ...configResult.config.compilerOptions,
-        ...typeScriptOptions.compilerOptions
+        ...typeScriptOptions.compilerOptions,
+        // Always include 'node' and merge with any user-specified types
+        types: [.../* @__PURE__ */ new Set(["node", ...configResult.config.compilerOptions?.types ?? [], ...typeScriptOptions.compilerOptions?.types ?? []])]
       }
     };
     const { options, fileNames, errors } = parseJsonConfigFileContent(baseConfig, sys2, directory);

package/dist/{LEZQQWX3.js → RBRXNRTQ.js}

@@ -3,7 +3,7 @@ import {
   Json,
   Paths,
   typeScriptExtensionExpression
-} from "./7FPDHUPW.js";
+} from "./UYXU5EAU.js";
 
 // src/plugins/decorator-metadata.ts
 import { dirname } from "node:path";

package/dist/{7FPDHUPW.js → UYXU5EAU.js}

@@ -61,6 +61,8 @@ var compilerOptionOverrides = {
   checkJs: false,
   // Skip declaration map generation. TODO - Would love to figure out how to combine them into a single file / entry point
   declarationMap: false,
+  // Force .d.ts output to outDir so the bundler can reliably find declaration files
+  declarationDir: void 0,
   // Skip type-checking all dependencies
   skipLibCheck: true,
   // Ensure TS2742 errors are visible when `true`. TODO - Figure out how to have this work with a value of `true`

package/dist/index.d.ts

@@ -188,9 +188,15 @@ type CachedDeclaration = {
 };
 /** Interface for build cache operations */
 interface BuildCache {
+    /** Invalidates the build cache */
     invalidate(): void;
+    /** Restores cached declaration files into the provided map */
     restore(target: Map<string, CachedDeclaration>): Promise<void>;
+    /** Saves declaration files to the cache */
     save(source: ReadonlyMap<string, CachedDeclaration>): Promise<void>;
+    /** Checks if the cache is valid */
+    isValid(): boolean;
+    /** Checks if a file path is the TypeScript build info file */
     isBuildInfoFile(filePath: AbsolutePath): boolean;
 }
 type TypeScriptConfiguration = Readonly<PrettyModify<TypeScriptOptions, {
@@ -236,6 +242,7 @@ type CompilerOptionOverrides = Readonly<{
     allowJs: false;
     checkJs: false;
     declarationMap: false;
+    declarationDir: undefined;
     skipLibCheck: true;
     preserveSymlinks: false;
     target: ScriptTarget.ESNext;

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   TypeScriptProject
-} from "./QG4L36TP.js";
-import "./7FPDHUPW.js";
+} from "./4BKT57QY.js";
+import "./UYXU5EAU.js";
 export {
   TypeScriptProject
 };

package/dist/tsbuild.js

@@ -2,8 +2,8 @@
 import {
   BuildError,
   TypeScriptProject
-} from "./QG4L36TP.js";
-import "./7FPDHUPW.js";
+} from "./4BKT57QY.js";
+import "./UYXU5EAU.js";
 
 // src/tsbuild.ts
 import { sys } from "typescript";
@@ -30,7 +30,7 @@ if (help) {
   process.exit(0);
 }
 if (version) {
-  console.log("1.3.2");
+  console.log("1.5.0");
   process.exit(0);
 }
 var typeScriptOptions = {

package/package.json

@@ -1,8 +1,30 @@
 {
   "name": "@d1g1tal/tsbuild",
-  "version": "1.3.2",
-  "packageManager": "pnpm@10.30.3",
+  "author": "D1g1talEntr0py",
+  "version": "1.5.0",
+  "license": "MIT",
   "description": "A fast, ESM-only TypeScript build tool combining the TypeScript API for type checking and declaration generation, esbuild for bundling, and SWC for decorator metadata.",
+  "homepage": "https://github.com/D1g1talEntr0py/tsbuild#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/D1g1talEntr0py/tsbuild.git"
+  },
+  "bugs": {
+    "url": "https://github.com/D1g1talEntr0py/tsbuild/issues"
+  },
+  "maintainers": [
+    {
+      "name": "D1g1talEntr0py",
+      "email": "jason.dimeo@gmail.com"
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
   "type": "module",
   "exports": {
     ".": {
@@ -12,47 +34,13 @@
   },
   "files": [
     "./dist",
-    "./schema.json"
+    "./schema.json",
+    "README.md",
+    "LICENSE"
   ],
   "bin": {
     "tsbuild": "./dist/tsbuild.js"
   },
-  "scripts": {
-    "prepare": "git config core.hooksPath .githooks",
-    "build": "tsx ./src/tsbuild.ts",
-    "build:watch": "tsx ./src/tsbuild.ts --watch",
-    "type-check": "tsx ./src/tsbuild.ts --noEmit",
-    "lint": "eslint ./src",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "pnpm lint && pnpm build"
-  },
-  "keywords": [
-    "typescript",
-    "build",
-    "bundler",
-    "esbuild",
-    "declarations",
-    "dts",
-    "esm"
-  ],
-  "author": "D1g1talEntr0py",
-  "license": "MIT",
-  "engines": {
-    "node": ">=20.16.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/D1g1talEntr0py/tsbuild.git"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "bugs": {
-    "url": "https://github.com/D1g1talEntr0py/tsbuild/issues"
-  },
-  "homepage": "https://github.com/D1g1talEntr0py/tsbuild#readme",
   "dependencies": {
     "@d1g1tal/watchr": "1.0.0",
     "esbuild": "^0.27.3",
@@ -60,17 +48,34 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.3.0",
+    "@types/node": "^25.3.5",
     "@typescript-eslint/eslint-plugin": "^8.56.1",
     "@typescript-eslint/parser": "^8.56.1",
     "@vitest/coverage-v8": "4.0.18",
-    "eslint": "^10.0.2",
+    "eslint": "^10.0.3",
     "eslint-plugin-jsdoc": "^62.7.1",
     "fs-monkey": "^1.1.0",
-    "memfs": "^4.56.10",
+    "memfs": "^4.56.11",
     "tsx": "^4.21.0",
     "typescript": "5.9.3",
     "typescript-eslint": "^8.56.1",
     "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "typescript",
+    "build",
+    "bundler",
+    "esbuild",
+    "declarations",
+    "dts",
+    "esm"
+  ],
+  "scripts": {
+    "build": "tsx ./src/tsbuild.ts",
+    "build:watch": "tsx ./src/tsbuild.ts --watch",
+    "type-check": "tsx ./src/tsbuild.ts --noEmit",
+    "lint": "eslint ./src",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   }
-}
+}