chore(build): migrate to tsdown workspace mode (#5738)

Replace per-package tsdown config spreading with native workspace mode:
- Add root tsdown.config.ts with workspace configuration
- Remove 60 standard tsdown.config.ts files that only spread base config
- Keep 7 configs with custom options (copy, unbundle, unused.ignore)
- Simplify root build script to just run tsdown once
- Delete tsdown.config.json (old JSON base config)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Build Process Improvements**
* Introduces a workspace-wide tsdown build/configuration flow; adds
workspace scripts (including a tsdown alias and clean-dist) and
centralizes defaults so most packages no longer need individual build
configs.

* **Breaking Changes**
* Many package-level build scripts and per-package tsdown configs were
removed; publishing or custom build workflows may require updating.

* **Documentation**
* Guidance updated: per-package config is optional — create one only for
custom behavior; example simplified.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: fengmk2

.github/workflows/ci.yml

@@ -163,7 +163,8 @@ jobs:
 
       - name: Run example tests
         if: ${{ matrix.node != '20' && matrix.os != 'windows-latest' }}
-        run: pnpm run example:test:all
+        run: |
+          pnpm run example:test:all
 
       - name: Code Coverage
         # skip on windows, it will hangup on codecov
@@ -176,9 +177,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # os: ['ubuntu-latest', 'macos-latest', 'windows-latest']
         os: ['ubuntu-latest', 'windows-latest']
-        node: ['22']
+        node: ['24']
         # 0-based index
         shardIndex: [0, 1, 2]
         shardTotal: [3]
@@ -207,7 +207,9 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Run tests
-        run: pnpm run --filter=./tools/egg-bin ci
+        run: |
+          pnpm build --workspace ./tools/egg-bin
+          pnpm run --filter ./tools/egg-bin ci
         env:
           # https://github.com/jamiebuilds/ci-parallel-vars
           CI_NODE_INDEX: ${{ matrix.shardIndex }}
@@ -251,7 +253,9 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Run tests
-        run: pnpm run --filter=./tools/scripts ci
+        run: |
+          pnpm build
+          pnpm run --filter=./tools/scripts ci
 
       - name: Code Coverage
         if: ${{ matrix.os != 'windows-latest' }}

.github/workflows/release.yml

@@ -72,14 +72,12 @@ jobs:
           cache: 'pnpm'
           registry-url: 'https://registry.npmjs.org'
 
-      - name: Re-install npm
-        # TODO: OIDC requires npm >=11.5.1.
-        # Until Node.js v24 is LTS (with npm 11 as the default), we need to bump.
-        run: npm install -g npm@11
-
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Run build
+        run: pnpm build
+
       - name: Configure Git
         run: |
           git config --local user.email "action@github.com"

CLAUDE.md

@@ -222,7 +222,6 @@ The framework follows a specific loading order:
 - **`pnpm-workspace.yaml`** - pnpm workspace configuration with catalog dependencies
 - **`package.json`** - Root monorepo configuration with pnpm scripts
 - **`tsconfig.json`** - Root TypeScript configuration for all packages (extends @eggjs/tsconfig)
-- **`tsconfig.build.json`** - Root build configuration (extends tsconfig.json)
 - **`packages/egg/package.json`** - Main egg package with hybrid CommonJS/ESM exports
 - **`packages/egg/tsconfig.json`** - Extends workspace root tsconfig.json
 - **`packages/egg/tsdown.config.ts`** - tsdown build configuration for unbundled ESM output
@@ -288,7 +287,6 @@ The framework extends Koa's context with Egg-specific features:
 2. Add package.json with workspace dependencies using `workspace:*`
 3. Create minimal TypeScript config files:
    - `tsconfig.json` → `{"extends": "../../tsconfig.json"}`
-   - `tsconfig.build.json` → `{"extends": "../../tsconfig.build.json"}`
 4. Add package reference to root tsconfig.json `references` array
 5. Update root pnpm-workspace.yaml if needed (plugins/\* is already included)
 6. Use `pnpm --filter=<package>` for package-specific commands
@@ -305,35 +303,38 @@ All Egg framework plugins should be placed in the `plugins/` directory:
   - `src/` - TypeScript source code
   - `test/` - Test suite (use Vitest for new plugins)
   - `package.json` with `eggPlugin` configuration
-  - `tsdown.config.ts` - Build configuration (see standard template below)
+  - `tsdown.config.ts` - Only needed if custom build options required (see below)
 
-#### Standard Plugin tsdown Configuration
+#### tsdown Workspace Configuration
 
-**IMPORTANT: All future plugins MUST use this tsdown configuration template** (based on `plugins/development/tsdown.config.ts`):
+**This monorepo uses tsdown workspace mode** for build configuration. The root `/tsdown.config.ts` defines shared defaults for all packages:
+
+- `entry: 'src/**/*.ts'` - Processes all TypeScript files in src directory
+- `unbundle: true` - Creates unbundled output (preserves file structure)
+- `dts: true` - Generates TypeScript declaration files
+- `exports.devExports: true` - Enables development-friendly exports
+- `unused.level: 'error'` - Error on unused dependencies
+- `publint` - Package linting enabled
+
+**Most plugins do NOT need a `tsdown.config.ts` file** - they inherit all settings from the root workspace config.
+
+**Only create a `tsdown.config.ts` if you need custom options** (e.g., copy assets, custom entry points, ignore unused deps):
 
 ```typescript
+// plugins/[plugin-name]/tsdown.config.ts - ONLY if custom options needed
 import { defineConfig } from 'tsdown';
 
 export default defineConfig({
-  entry: 'src/**/*.ts',
-  unbundle: true,
-  unused: {
-    level: 'error',
-  },
-  dts: true,
-  exports: {
-    devExports: true,
-  },
+  // Only specify options that differ from workspace defaults
+  copy: [
+    {
+      from: 'src/assets/template.html',
+      to: 'dist/assets/template.html',
+    },
+  ],
 });
 ```
 
-This configuration ensures:
-
-- **`entry: 'src/**/\*.ts'`\*\* - Processes all TypeScript files in src directory
-- **`unbundle: true`** - Creates unbundled output (preserves file structure)
-- **`dts: true`** - Generates TypeScript declaration files
-- **`exports.devExports: true`** - Enables development-friendly exports
-
 #### Standard Plugin TypeScript Types
 
 **IMPORTANT: All plugins MUST define a `src/types.ts` file** that extends the Egg module declarations:
@@ -427,11 +428,8 @@ Plugins should configure their package.json following this pattern:
   },
   "files": ["dist"],
   "scripts": {
-    "build": "tsdown && rimraf dist *.tsbuildinfo && tsc -p tsconfig.build.json",
-    "typecheck": "tsgo --noEmit && tsc --noEmit",
-    "lint": "oxlint --type-aware",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm run build"
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
   }
 }
 ```
@@ -471,7 +469,7 @@ Tool packages (like egg-bin) should be placed in the `tools/` directory:
 - Use `oxlint --type-aware` for enhanced TypeScript checking
 - oxlint automatically respects `.gitignore` patterns for file exclusion
 - Package-specific scripts:
-  - `"typecheck": "tsgo --noEmit && tsc --noEmit"` - Pure TypeScript type checking
+  - `"typecheck": "tsgo --noEmit"` - Pure TypeScript type checking
   - `"lint": "oxlint --type-aware"` - Linting with type awareness
 - Remove any `.eslintrc` or `.eslintrc.js` files when migrating packages
 
@@ -509,10 +507,6 @@ Tool packages (like egg-bin) should be placed in the `tools/` directory:
   - Uses `${configDir}` variable for dynamic path resolution
   - Includes project `references` array listing all sub-packages
   - Sets `composite: true` and `incremental: true` for project references
-- `tsconfig.build.json` - Build-specific configuration
-  - Extends from root `tsconfig.json`
-  - Defines `rootDir` as `${configDir}/src` and `outDir` as `${configDir}/dist`
-  - Excludes test files, dist directories, and config files
 
 **Sub-Project Configuration Pattern:**
 
@@ -525,13 +519,6 @@ All packages, plugins, and tools MUST follow this minimal pattern:
 }
 ```
 
-```json
-// packages/*/tsconfig.build.json, plugins/*/tsconfig.build.json
-{
-  "extends": "../../tsconfig.build.json"
-}
-```
-
 **Key Requirements:**
 
 - **Keep it minimal** - Sub-project configs should ONLY contain the `extends` field
@@ -852,7 +839,7 @@ NODE_OPTIONS='--inspect-brk' pnpm --filter=egg run test
    - Add `"oxlint": "catalog:"` to devDependencies
 2. Delete `.eslintrc`, `.eslintrc.js`, or `.eslintrc.json` files
 3. Update scripts in package.json:
-   - Add `"typecheck": "tsgo --noEmit && tsc --noEmit"` for TypeScript type checking
+   - Add `"typecheck": "tsgo --noEmit"` for TypeScript type checking
    - Change `"lint": "eslint ..."` to `"lint": "oxlint --type-aware"`
    - Add `"lint:fix": "npm run lint -- --fix"`
 4. Ensure both type checking and linting are run:

examples/helloworld-commonjs/package.json

@@ -7,9 +7,6 @@
   "scripts": {
     "dev": "egg-bin dev",
     "debug": "egg-bin debug",
-    "test": "egg-bin test",
-    "cov": "egg-bin cov",
-    "lint": "oxlint",
     "ci": "pnpm run lint && pnpm run cov",
     "start": "egg-scripts start --daemon",
     "stop": "egg-scripts stop"
@@ -18,8 +15,7 @@
     "egg": "workspace:*"
   },
   "devDependencies": {
-    "@eggjs/bin": "workspace:*",
-    "oxlint": "catalog:"
+    "@eggjs/bin": "workspace:*"
   },
   "engines": {
     "node": ">=22.18.0"

examples/helloworld-tegg/package.json

@@ -44,7 +44,7 @@
     "prepublishOnly": "pnpm run build",
     "start": "egg-scripts start --daemon",
     "stop": "egg-scripts stop",
-    "typecheck": "tsgo --noEmit && tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "build": "tsdown"
   },
   "dependencies": {

examples/helloworld-typescript/package.json

@@ -32,7 +32,7 @@
     "prepublishOnly": "pnpm run build",
     "start": "egg-scripts start --daemon",
     "stop": "egg-scripts stop",
-    "typecheck": "tsgo --noEmit && tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "build": "tsdown"
   },
   "dependencies": {

package.json

@@ -10,19 +10,19 @@
   },
   "type": "module",
   "scripts": {
-    "clean": "pnpm -r --parallel run clean && rimraf packages/*/dist plugins/*/dist tools/*/dist examples/*/dist tegg/**/dist **/*/*.tsbuildinfo",
-    "build": "pnpm clean && pnpm -r run build",
-    "build:parallel": "pnpm clean && pnpm -r --parallel run build",
+    "clean-dist": "pnpm -r --parallel exec rimraf dist",
+    "clean": "pnpm -r --parallel run clean && pnpm clean-dist",
+    "build": "tsdown",
+    "prelint": "pnpm clean-dist",
     "lint": "oxlint --type-aware --type-check --quiet",
     "fmt": "oxfmt",
     "typecheck": "pnpm clean && pnpm -r run typecheck",
-    "typecheck:parallel": "pnpm clean && pnpm -r --parallel run typecheck",
     "fmtcheck": "oxfmt --check .",
     "pretest": "pnpm run clean && pnpm -r run pretest",
-    "test": "vitest run --bail 1 --retry 2",
+    "test": "vitest run --bail 1 --retry 2 --testTimeout 20000 --hookTimeout 20000",
     "test:cov": "pnpm run test --coverage",
     "preci": "pnpm -r --parallel run pretest",
-    "ci": "vitest run --bail 1 --retry 2 --coverage --testTimeout 20000 --hookTimeout 20000",
+    "ci": "pnpm run test --coverage",
     "site:dev": "pnpm --filter=site run dev",
     "site:build": "pnpm --filter=site run build",
     "puml": "puml . --dest ./site",
@@ -60,14 +60,15 @@
     "publint": "catalog:",
     "rimraf": "catalog:",
     "semver": "catalog:",
+    "tsdown": "catalog:",
     "tsx": "catalog:",
     "typescript": "catalog:",
     "urllib": "catalog:",
     "vitest": "catalog:"
   },
   "lint-staged": {
     "*": [
-      "oxfmt",
+      "oxfmt --no-error-on-unmatched-pattern",
       "oxlint --type-aware --fix"
     ]
   },

packages/cluster/package.json

@@ -41,11 +41,9 @@
     }
   },
   "scripts": {
-    "build": "tsdown && rimraf dist *.tsbuildinfo && tsc -p tsconfig.build.json",
     "lint": "oxlint",
-    "typecheck": "tsgo --noEmit && tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm run build"
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
     "@eggjs/utils": "workspace:*",

packages/cluster/tsconfig.build.json

@@ -1,14 +1,9 @@
-import { defineConfig, type UserConfig } from 'tsdown';
+import { defineConfig } from 'tsdown';
 
-import baseConfig from '../../tsdown.config.json' with { type: 'json' };
-
-const config: UserConfig = defineConfig({
-  ...(baseConfig as UserConfig),
+export default defineConfig({
   entry: {
     index: 'src/index.ts',
     agent_worker: 'src/agent_worker.ts',
     app_worker: 'src/app_worker.ts',
   },
 });
-
-export default config;