feat: bundle esm + cjs variants of runtime packages using tsdown (#452)

adopts the use of https://tsdown.dev/ to bundle the runtime packages as
distinct CJS and ESM distributions.

increasingly, we've run into issues where mixing and matching ESM/CJS
creates annoying build errors, such as the `axios` type-mismatches
between their CJS and ESM typings that we had to patch out.

similar issues occurred whilst updating `@koa/router` to v15, and so
decided it was time to address.

the primary downside, is that the `dist` files will no longer mirror the
`src` structure.

this will require careful testing of package publishing and installation
to ensure there are no regressions prior to release.

Author: mnahkies

.github/workflows/ci.yml

@@ -27,8 +27,8 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - run: node ./scripts/generate-ajv-validator.js
-      - run: pnpm tsc -b tsconfig.json
+      - run: pnpm run build
+
       - run: pnpm ci-lint
 
       - name: Check for uncommitted changes
@@ -84,7 +84,7 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - run: pnpm --filter @nahkies/openapi-code-generator-documentation build
+      - run: pnpm run build:docs
 
   unit:
     needs: build

package.json

@@ -21,7 +21,7 @@
     "docs:generate": "node ./scripts/generate-toc.mjs",
     "refresh": "./scripts/refresh-data.sh",
     "lint": "biome check --fix .",
-    "build": "node ./scripts/generate-ajv-validator.js && tsc -b tsconfig.json",
+    "build": "node ./scripts/generate-ajv-validator.js && pnpm -r --workspace-concurrency=4 run bundle && tsc -b tsconfig.json",
     "build:docs": "pnpm --filter @nahkies/openapi-code-generator-documentation build",
     "build:watch": "tsc -b tsconfig.json -w",
     "test": "jest",

packages/typescript-axios-runtime/package.json

@@ -18,14 +18,20 @@
   },
   "exports": {
     "./main": {
-      "require": "./dist/main.js",
-      "import": "./dist/main.js",
-      "types": "./dist/main.d.ts"
+      "import": {
+        "types": "./dist/esm/main.d.mts",
+        "default": "./dist/esm/main.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/main.d.cts",
+        "default": "./dist/cjs/main.cjs"
+      }
     }
   },
   "scripts": {
     "clean": "rm -rf ./dist && rm tsconfig.tsbuildinfo",
     "build": "tsc -p ./tsconfig.json",
+    "bundle": "tsdown",
     "test": "jest"
   },
   "dependencies": {
@@ -39,6 +45,7 @@
     "@jest/globals": "^30.3.0",
     "axios": "^1.15.2",
     "jest": "^30.3.0",
+    "tsdown": "^0.21.10",
     "typescript": "^6.0.3"
   },
   "files": [

packages/typescript-axios-runtime/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "./dist",
-    "rootDir": "./src"
+    "rootDir": "./src",
+    "emitDeclarationOnly": true
   },
   "include": ["src/**/*"],
   "references": [

packages/typescript-axios-runtime/tsdown.config.mts

@@ -0,0 +1,20 @@
+import {defineConfig} from "tsdown"
+import packageJson from "./package.json" with {type: "json"}
+
+export default defineConfig({
+  name: packageJson.name,
+  entry: ["./src/main.ts"],
+
+  target: "esnext",
+  dts: true,
+  sourcemap: true,
+
+  format: {
+    esm: {
+      outDir: "./dist/esm",
+    },
+    cjs: {
+      outDir: "./dist/cjs",
+    },
+  },
+})

packages/typescript-common-runtime/package.json

@@ -18,34 +18,60 @@
   },
   "exports": {
     "./errors": {
-      "require": "./dist/errors.js",
-      "import": "./dist/errors.js",
-      "types": "./dist/errors.d.ts"
+      "import": {
+        "types": "./dist/esm/errors.d.mts",
+        "default": "./dist/esm/errors.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/errors.d.cts",
+        "default": "./dist/cjs/errors.cjs"
+      }
     },
     "./validation": {
-      "require": "./dist/validation.js",
-      "import": "./dist/validation.js",
-      "types": "./dist/validation.d.ts"
+      "import": {
+        "types": "./dist/esm/validation.d.mts",
+        "default": "./dist/esm/validation.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/validation.d.cts",
+        "default": "./dist/cjs/validation.cjs"
+      }
     },
     "./types": {
-      "require": "./dist/types.js",
-      "import": "./dist/types.js",
-      "types": "./dist/types.d.ts"
+      "import": {
+        "types": "./dist/esm/types.d.mts",
+        "default": "./dist/esm/types.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/types.d.cts",
+        "default": "./dist/cjs/types.cjs"
+      }
     },
     "./query-parser": {
-      "require": "./dist/query-parser.js",
-      "import": "./dist/query-parser.js",
-      "types": "./dist/query-parser.d.ts"
+      "import": {
+        "types": "./dist/esm/query-parser.d.mts",
+        "default": "./dist/esm/query-parser.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/query-parser.d.cts",
+        "default": "./dist/cjs/query-parser.cjs"
+      }
     },
     "./request-bodies": {
-      "require": "./dist/request-bodies/index.js",
-      "import": "./dist/request-bodies/index.js",
-      "types": "./dist/request-bodies/index.d.ts"
+      "import": {
+        "types": "./dist/esm/request-bodies/index.d.mts",
+        "default": "./dist/esm/request-bodies/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/request-bodies/index.d.cts",
+        "default": "./dist/cjs/request-bodies/index.cjs"
+      }
     }
   },
   "scripts": {
     "clean": "rm -rf ./dist && rm tsconfig.tsbuildinfo",
     "build": "tsc -p ./tsconfig.json",
+    "bundle": "tsdown",
     "test": "jest"
   },
   "dependencies": {
@@ -68,6 +94,7 @@
     "@jest/globals": "^30.3.0",
     "jest": "^30.3.0",
     "joi": "^18.1.2",
+    "tsdown": "^0.21.10",
     "typescript": "^6.0.3",
     "zod": "^3.25.76"
   },

packages/typescript-common-runtime/tsconfig.json

@@ -2,7 +2,8 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "rootDir": "./src",
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "emitDeclarationOnly": true
   },
   "include": ["src/**/*"],
   "references": []

packages/typescript-common-runtime/tsdown.config.mts

@@ -0,0 +1,26 @@
+import {defineConfig} from "tsdown"
+import packageJson from "./package.json" with {type: "json"}
+
+export default defineConfig({
+  name: packageJson.name,
+  entry: [
+    "./src/errors.ts",
+    "./src/validation.ts",
+    "./src/types.ts",
+    "./src/query-parser.ts",
+    "./src/request-bodies/index.ts",
+  ],
+  target: "esnext",
+
+  format: {
+    esm: {
+      outDir: "./dist/esm",
+    },
+    cjs: {
+      outDir: "./dist/cjs",
+    },
+  },
+
+  dts: true,
+  sourcemap: true,
+})

packages/typescript-express-runtime/package.json

@@ -18,35 +18,61 @@
   },
   "exports": {
     "./errors": {
-      "require": "./dist/errors.js",
-      "import": "./dist/errors.js",
-      "types": "./dist/errors.d.ts"
+      "import": {
+        "types": "./dist/esm/errors.d.mts",
+        "default": "./dist/esm/errors.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/errors.d.cts",
+        "default": "./dist/cjs/errors.cjs"
+      }
     },
     "./server": {
-      "require": "./dist/server.js",
-      "import": "./dist/server.js",
-      "types": "./dist/server.d.ts"
+      "import": {
+        "types": "./dist/esm/server.d.mts",
+        "default": "./dist/esm/server.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/server.d.cts",
+        "default": "./dist/cjs/server.cjs"
+      }
     },
     "./joi": {
-      "require": "./dist/joi.js",
-      "import": "./dist/joi.js",
-      "types": "./dist/joi.d.ts"
+      "import": {
+        "types": "./dist/esm/joi.d.mts",
+        "default": "./dist/esm/joi.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/joi.d.cts",
+        "default": "./dist/cjs/joi.cjs"
+      }
     },
     "./zod-v3": {
-      "require": "./dist/zod-v3.js",
-      "import": "./dist/zod-v3.js",
-      "types": "./dist/zod-v3.d.ts"
+      "import": {
+        "types": "./dist/esm/zod-v3.d.mts",
+        "default": "./dist/esm/zod-v3.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/zod-v3.d.cts",
+        "default": "./dist/cjs/zod-v3.cjs"
+      }
     },
     "./zod-v4": {
-      "require": "./dist/zod-v4.js",
-      "import": "./dist/zod-v4.js",
-      "types": "./dist/zod-v4.d.ts"
+      "import": {
+        "types": "./dist/esm/zod-v4.d.mts",
+        "default": "./dist/esm/zod-v4.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/zod-v4.d.cts",
+        "default": "./dist/cjs/zod-v4.cjs"
+      }
     }
   },
   "scripts": {
     "clean": "rm -rf ./dist && rm tsconfig.tsbuildinfo",
     "dev": "nodemon --watch ./src -e ts --delay 2 --exec 'pnpm build'",
     "build": "tsc -p ./tsconfig.json",
+    "bundle": "tsdown",
     "test": "jest"
   },
   "dependencies": {
@@ -80,6 +106,7 @@
     "body-parser": "^2.2.2",
     "jest": "^30.3.0",
     "joi": "^18.1.2",
+    "tsdown": "^0.21.10",
     "typescript": "^6.0.3",
     "zod": "^3.25.76"
   },

packages/typescript-express-runtime/src/server.ts

@@ -1,7 +1,6 @@
 import type {Server} from "node:http"
 import type {AddressInfo, ListenOptions} from "node:net"
 import type {Res, StatusCode} from "@nahkies/typescript-common-runtime/types"
-import {ExpressRuntimeError} from "@nahkies/typescript-express-runtime/errors"
 import type {OptionsJson, OptionsText, OptionsUrlencoded} from "body-parser"
 import Cors, {type CorsOptions, type CorsOptionsDelegate} from "cors"
 import type {Response} from "express"
@@ -13,6 +12,7 @@ import express, {
   type RequestHandler,
   type Router,
 } from "express"
+import {ExpressRuntimeError} from "./errors"
 
 export {parseQueryParameters} from "@nahkies/typescript-common-runtime/query-parser"