@web-ts-toolkit/express-runtime 0.24.0 → 0.26.0

package/README.md

@@ -23,10 +23,12 @@ pnpm add @web-ts-toolkit/express-runtime express
 - `startLocalServer()` — `http.createServer` + `listen` with friendly
   `EADDRINUSE` / `EACCES` errors, optional graceful `SIGINT` / `SIGTERM`
   shutdown that drains in-flight requests, and a configurable timeout.
-- CLI binary with three subcommands:
+- CLI binary with five subcommands:
   - `dev` — run an Express app as a local dev server
-  - `build` — bundle the app as a serverless handler
-  - `start` — smoke-test the bundled handler locally by translating HTTP ↔ serverless events
+  - `build` — bundle the app as a local runtime module
+  - `start` — start the bundled local app module
+  - `build-serverless` — bundle the app as a serverless handler
+  - `start-serverless` — smoke-test the bundled handler locally by translating HTTP ↔ serverless events
 
 ## Quick Start
 
@@ -131,19 +133,19 @@ npx tsx ./node_modules/@web-ts-toolkit/express-runtime/dist/cli.js dev ./src/app
 > be placed at the top level of your app module since `dev` does not expose an
 > `init` hook.
 
-### CLI — build (serverless bundle)
+### CLI — build (local runtime bundle)
 
-The `build` command generates a temporary serverless entry that wraps the app
-with `createServerlessHandler`, then bundles it into a deployment-ready file:
+The `build` command generates a temporary runtime entry that re-exports the app
+and optional `init` hook, then bundles it into a local runtime file:
 
 ```sh
-npx wtt-express-runtime build ./src/app.ts --out-dir netlify/functions
+npx wtt-express-runtime build ./src/app.ts --out-dir dist
 ```
 
 With an optional init hook (DB connections, cache warmup, etc.):
 
 ```sh
-npx wtt-express-runtime build ./src/app.ts --init ./src/init.ts --out-dir netlify/functions
+npx wtt-express-runtime build ./src/app.ts --init ./src/init.ts --out-dir dist
 ```
 
 ```ts
@@ -153,29 +155,54 @@ export default async () => {
 };
 ```
 
-This produces `netlify/functions/handler.js` (configurable via `--out-name`)
-that exports a `handler` function compatible with Netlify, Vercel, AWS Lambda,
-and any platform that calls `(event, context)`.
+This produces `dist/app.js` (configurable via `--out-name`) that default-exports
+the Express app and, when `--init` is used, also exports `init` for the `start`
+command to run before listening.
 
 > `express` is always external; additional externals can be added via
 > `--external`.
 
-### CLI — start (run a bundled handler locally)
+### CLI — start (run a bundled app locally)
 
-The `start` command runs a bundled serverless handler locally by translating
-HTTP requests into serverless events and the handler's results back into HTTP
-responses — letting you smoke-test the exact `build` output without a
-serverless platform:
+The `start` command runs the `build` output locally with `startLocalServer()`:
 
 ```sh
 npx wtt-express-runtime build ./src/app.ts --out-dir dist
-npx wtt-express-runtime start ./dist/handler.js --port 9000 --env .env
+npx wtt-express-runtime start ./dist/app.js --port 9000 --env .env
+```
+
+The bundled app module must default-export an Express app (or export it as
+`app`). If it exports `init`, that hook runs once before the server starts
+listening.
+
+### CLI — build-serverless (serverless bundle)
+
+The `build-serverless` command preserves the previous serverless bundling flow:
+
+```sh
+npx wtt-express-runtime build-serverless ./src/app.ts --out-dir netlify/functions
 ```
 
-The handler module must export a `handler` function (named or default) that
-accepts `(event, context)` and returns a result with `statusCode`, `headers`,
-and `body` — the same shape produced by `createServerlessHandler` via
-`serverless-http`.
+With an optional init hook:
+
+```sh
+npx wtt-express-runtime build-serverless ./src/app.ts --init ./src/init.ts --out-dir netlify/functions
+```
+
+This produces `netlify/functions/handler.js` (configurable via `--out-name`)
+that exports a `handler` function compatible with Netlify, Vercel, AWS Lambda,
+and any platform that calls `(event, context)`.
+
+### CLI — start-serverless (run a bundled handler locally)
+
+The `start-serverless` command runs a bundled serverless handler locally by
+translating HTTP requests into serverless events and the handler's results back
+into HTTP responses:
+
+```sh
+npx wtt-express-runtime build-serverless ./src/app.ts --out-dir dist
+npx wtt-express-runtime start-serverless ./dist/handler.js --port 9000 --env .env
+```
 
 > The adapter passes the raw request body as a Buffer (no body parsing) so the
 > handler's request hook, including the serverless-http #305 workaround, runs
@@ -298,11 +325,13 @@ interface Logger {
 
 Omitting `<command>` defaults to `dev` for backward compatibility.
 
-| Command | Description                                                                         |
-| ------- | ----------------------------------------------------------------------------------- |
-| `dev`   | Run the Express app as a local dev server (`http.createServer` + graceful shutdown) |
-| `build` | Bundle the Express app as a serverless handler                                      |
-| `start` | Run a bundled serverless handler locally (HTTP ↔ serverless event adapter)          |
+| Command            | Description                                                                         |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| `dev`              | Run the Express app as a local dev server (`http.createServer` + graceful shutdown) |
+| `build`            | Bundle the Express app as a local runtime module                                    |
+| `start`            | Run a bundled local app module with `startLocalServer()`                            |
+| `build-serverless` | Bundle the Express app as a serverless handler                                      |
+| `start-serverless` | Run a bundled serverless handler locally (HTTP ↔ serverless event adapter)          |
 
 #### dev options
 
@@ -326,7 +355,7 @@ Omitting `<command>` defaults to `dev` for backward compatibility.
 | `<app-module>`        | Module path whose **default export** is an Express app (sync, not async factory) |
 | `--init <path>`       | Init hook module (default export, async function) called once per cold start     |
 | `--out-dir <path>`    | Output directory (default: `dist`)                                               |
-| `--out-name <name>`   | Output filename without extension (default: `handler`)                           |
+| `--out-name <name>`   | Output filename without extension (default: `app`)                               |
 | `--format <cjs\|esm>` | Output format (default: `cjs`)                                                   |
 | `--target <target>`   | Compilation target (default: `node22`)                                           |
 | `--external <pkg>`    | Mark package as external (repeatable; `express` is always external)              |
@@ -334,15 +363,40 @@ Omitting `<command>` defaults to `dev` for backward compatibility.
 
 #### start options
 
-| Option                    | Description                                                                                |
-| ------------------------- | ------------------------------------------------------------------------------------------ |
-| `<handler-module>`        | JS/CJS module path exporting `handler` (named or default) — the output of `build`          |
-| `--port <number>`         | Port or named pipe (default: `process.env.PORT` or `8080`)                                 |
-| `--host <hostname>`       | Hostname to bind (default: `process.env.HOST` or `0.0.0.0`)                                |
-| `--no-signals`            | Disable `SIGINT` / `SIGTERM` handler registration                                          |
-| `--shutdown-timeout <ms>` | Max ms to wait for in-flight requests (default: `5000`)                                    |
-| `--require <module>`      | Module(s) to preload before handler load (repeatable; comma-separated values supported)    |
-| `--env <path>`            | Env file(s) to load before handler load (repeatable; existing env vars are not overridden) |
+| Option                    | Description                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `<app-module>`            | JS/CJS module path default-exporting an Express app (or exporting `app`) — the output of `build` |
+| `--port <number>`         | Port or named pipe (default: `process.env.PORT` or `8080`)                                       |
+| `--host <hostname>`       | Hostname to bind (default: `process.env.HOST` or `0.0.0.0`)                                      |
+| `--no-signals`            | Disable `SIGINT` / `SIGTERM` handler registration                                                |
+| `--shutdown-timeout <ms>` | Max ms to wait for in-flight requests (default: `5000`)                                          |
+| `--require <module>`      | Module(s) to preload before app load (repeatable; comma-separated values supported)              |
+| `--env <path>`            | Env file(s) to load before app load (repeatable; existing env vars are not overridden)           |
+
+#### build-serverless options
+
+| Option                | Description                                                                      |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `<app-module>`        | Module path whose **default export** is an Express app (sync, not async factory) |
+| `--init <path>`       | Init hook module (default export, async function) called once per cold start     |
+| `--out-dir <path>`    | Output directory (default: `dist`)                                               |
+| `--out-name <name>`   | Output filename without extension (default: `handler`)                           |
+| `--format <cjs\|esm>` | Output format (default: `cjs`)                                                   |
+| `--target <target>`   | Compilation target (default: `node22`)                                           |
+| `--external <pkg>`    | Mark package as external (repeatable; `express` is always external)              |
+| `--no-clean`          | Don't clean the output directory before building                                 |
+
+#### start-serverless options
+
+| Option                    | Description                                                                                  |
+| ------------------------- | -------------------------------------------------------------------------------------------- |
+| `<handler-module>`        | JS/CJS module path exporting `handler` (named or default) — the output of `build-serverless` |
+| `--port <number>`         | Port or named pipe (default: `process.env.PORT` or `8080`)                                   |
+| `--host <hostname>`       | Hostname to bind (default: `process.env.HOST` or `0.0.0.0`)                                  |
+| `--no-signals`            | Disable `SIGINT` / `SIGTERM` handler registration                                            |
+| `--shutdown-timeout <ms>` | Max ms to wait for in-flight requests (default: `5000`)                                      |
+| `--require <module>`      | Module(s) to preload before handler load (repeatable; comma-separated values supported)      |
+| `--env <path>`            | Env file(s) to load before handler load (repeatable; existing env vars are not overridden)   |
 
 #### global options
 
@@ -355,11 +409,12 @@ The `dev` command sets `exitAfterShutdown: true` so `SIGINT` / `SIGTERM` cleanly
 exit the process after the server drains. TypeScript app modules require a TS
 loader (see the Quick Start CLI section for a `tsx` invocation).
 
-The `build` command generates a temporary entry file that imports the app
-module and wraps it with `createServerlessHandler`, then produces a
-self-contained bundle. `express` is always external; all other dependencies
-(including `@web-ts-toolkit/express-runtime` and `serverless-http`) are
-bundled into the output unless marked external via `--external`.
+The `build` command generates a temporary entry file that re-exports the app
+module and optional `init` hook, then produces a local runtime bundle. The
+`build-serverless` command instead wraps the app with `createServerlessHandler`
+and bundles the serverless runtime. `express` is always external; all other
+dependencies are bundled into the output unless marked external via
+`--external`.
 
 ## License
 

package/cli.js

@@ -208,7 +208,7 @@ function readValue(argv, index, name) {
 function printHelp() {
   console.log(`wtt-express-runtime
 
-Run an Express app locally, bundle it as a serverless handler, or run the bundle.
+Run an Express app locally, bundle it for local or serverless runtimes, or run the bundle.
 
 Usage:
   wtt-express-runtime <command> <app-module> [options]
@@ -216,8 +216,10 @@ Usage:
 
 Commands:
   dev                           Run the Express app as a local dev server
-  build                         Bundle the Express app as a serverless handler
-  start                         Run a bundled serverless handler locally
+  build                         Bundle the Express app as a local app module
+  start                         Run a bundled local app module
+  build-serverless              Bundle the Express app as a serverless handler
+  start-serverless              Run a bundled serverless handler locally
 
 Dev options:
   --port <number>               Port or named pipe (default: process.env.PORT or 8080)
@@ -233,13 +235,30 @@ Dev options:
 Build options:
   --init <path>                 Init hook module (default export, async function)
   --out-dir <path>              Output directory (default: dist)
-  --out-name <name>             Output filename without extension (default: handler)
+  --out-name <name>             Output filename without extension (default: app)
   --format <cjs|esm>            Output format (default: cjs)
   --target <target>             Compilation target (default: node22)
   --external <pkg>              Mark package as external (repeatable; express always external)
   --no-clean                    Don't clean the output directory before building
 
 Start options:
+  --port <number>               Port or named pipe (default: process.env.PORT or 8080)
+  --host <hostname>             Hostname to bind (default: process.env.HOST or 0.0.0.0)
+  --no-signals                  Disable SIGINT/SIGTERM handler registration
+  --shutdown-timeout <ms>       Max ms to wait for in-flight requests (default: 5000)
+  --require <module>            Module(s) to preload before app load (repeatable)
+  --env <path>                  Env file(s) to load (repeatable; existing env vars are not overridden)
+
+Build-serverless options:
+  --init <path>                 Init hook module (default export, async function)
+  --out-dir <path>              Output directory (default: dist)
+  --out-name <name>             Output filename without extension (default: handler)
+  --format <cjs|esm>            Output format (default: cjs)
+  --target <target>             Compilation target (default: node22)
+  --external <pkg>              Mark package as external (repeatable; express always external)
+  --no-clean                    Don't clean the output directory before building
+
+Start-serverless options:
   --port <number>               Port or named pipe (default: process.env.PORT or 8080)
   --host <hostname>             Hostname to bind (default: process.env.HOST or 0.0.0.0)
   --no-signals                  Disable SIGINT/SIGTERM handler registration
@@ -255,10 +274,12 @@ Examples:
   wtt-express-runtime dev ./dist/app.js
   wtt-express-runtime dev ./dist/app.js --port 3000 --host localhost
   wtt-express-runtime dev ./src/app.ts --env .env --require tsconfig-paths/register --watch ./src,./shared
-  wtt-express-runtime build ./src/app.ts --out-dir netlify/functions
-  wtt-express-runtime build ./src/app.ts --init ./src/init.ts --format esm
-  wtt-express-runtime start ./netlify/functions/handler.js --port 9000 --env .env
-  wtt-express-runtime build ./src/app.ts && wtt-express-runtime start ./dist/handler.js
+  wtt-express-runtime build ./src/app.ts --out-dir dist
+  wtt-express-runtime start ./dist/app.js --port 3000 --env .env
+  wtt-express-runtime build-serverless ./src/app.ts --out-dir netlify/functions
+  wtt-express-runtime build-serverless ./src/app.ts --init ./src/init.ts --format esm
+  wtt-express-runtime start-serverless ./netlify/functions/handler.js --port 9000 --env .env
+  wtt-express-runtime build-serverless ./src/app.ts && wtt-express-runtime start-serverless ./dist/handler.js
 
 Notes:
   - In dev mode, the CLI evaluates arbitrary code from <app-module> in the current process.
@@ -269,9 +290,11 @@ Notes:
     For advanced dotenv features (multiline, expansion), --require dotenv/config instead.
   - --watch forks a child process running the same CLI without --watch. On file change,
     the child is killed (SIGTERM) and respawned after the debounce delay.
-  - In build mode, express is always external. Add more externals with --external.
-  - In start mode, the bundled handler file must be a JS/CJS module whose "handler"
-    export (or default export) is a function: (event, context) => Promise<result>.
+  - In build/build-serverless mode, express is always external. Add more externals with --external.
+  - In start mode, the bundled app file must default-export an Express app (or export it as "app").
+    If the bundle exports "init", it runs before the server starts listening.
+  - In start-serverless mode, the bundled handler file must be a JS/CJS module whose
+    "handler" export (or default export) is a function: (event, context) => Promise<result>.
   - Init logic for dev mode (DB connections, etc.): add at the top level of your app module.
 `);
 }
@@ -282,7 +305,7 @@ function isHelp(arg) {
   return arg === "-h" || arg === "--help";
 }
 function isSubcommand(arg) {
-  return arg === "dev" || arg === "build" || arg === "start";
+  return arg === "dev" || arg === "build" || arg === "start" || arg === "build-serverless" || arg === "start-serverless";
 }
 var DEFAULT_WATCH_EXTENSIONS = ["ts", "js", "mjs", "cjs", "json"];
 var DEFAULT_WATCH_DELAY = 500;
@@ -423,13 +446,25 @@ function parseDevArgs(argv) {
     watchDelay: watchDelay ?? DEFAULT_WATCH_DELAY
   };
 }
-function parseStartArgs(argv) {
+function parseStartLikeArgs(argv, subcommandName) {
   for (const arg of argv) {
     if (arg === "--watch" || arg.startsWith("--watch=") || arg === "--ext" || arg.startsWith("--ext=") || arg === "--delay" || arg.startsWith("--delay=")) {
-      throw new Error(`--watch/--ext/--delay are not supported with the start subcommand`);
+      throw new Error(`--watch/--ext/--delay are not supported with the ${subcommandName} subcommand`);
     }
   }
-  const result = parseDevArgs(argv);
+  return parseDevArgs(argv);
+}
+function parseStartArgs(argv) {
+  const result = parseStartLikeArgs(argv, "start");
+  return {
+    appPath: result.appPath,
+    options: result.options,
+    require: result.require,
+    env: result.env
+  };
+}
+function parseStartServerlessArgs(argv) {
+  const result = parseStartLikeArgs(argv, "start-serverless");
   return {
     handlerPath: result.appPath,
     options: result.options,
@@ -437,13 +472,13 @@ function parseStartArgs(argv) {
     env: result.env
   };
 }
-function parseBuildArgs(argv) {
+function parseBuildArgs(argv, outNameDefault) {
   let appPath;
   const external = [];
   const result = {
     initPath: void 0,
     outDir: "dist",
-    outName: "handler",
+    outName: outNameDefault,
     format: "cjs",
     target: "node22",
     external,
@@ -538,6 +573,12 @@ function parseBuildArgs(argv) {
   }
   return { appPath, ...result };
 }
+function parseLocalBuildArgs(argv) {
+  return parseBuildArgs(argv, "app");
+}
+function parseBuildServerlessArgs(argv) {
+  return parseBuildArgs(argv, "handler");
+}
 function parseArgs(argv) {
   if (argv.length === 0) {
     printHelp();
@@ -557,10 +598,16 @@ function parseArgs(argv) {
     if (first === "dev") {
       return { subcommand: "dev", dev: parseDevArgs(rest) };
     }
+    if (first === "build") {
+      return { subcommand: "build", build: parseLocalBuildArgs(rest) };
+    }
     if (first === "start") {
       return { subcommand: "start", start: parseStartArgs(rest) };
     }
-    return { subcommand: "build", build: parseBuildArgs(rest) };
+    if (first === "build-serverless") {
+      return { subcommand: "build-serverless", buildServerless: parseBuildServerlessArgs(rest) };
+    }
+    return { subcommand: "start-serverless", startServerless: parseStartServerlessArgs(rest) };
   }
   return { subcommand: "dev", dev: parseDevArgs(argv) };
 }
@@ -716,7 +763,8 @@ function runWithWatch(args) {
   process.on("SIGTERM", shutdown);
   spawnChild();
 }
-var TEMP_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
+var TEMP_BUILD_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
+var TEMP_SERVERLESS_ENTRY_FILENAME = ".express-runtime-build-serverless-entry.ts";
 function generateServerlessEntry(appPath, initPath) {
   const absAppPath = (0, import_node_path.resolve)(process.cwd(), appPath);
   const absInitPath = initPath ? (0, import_node_path.resolve)(process.cwd(), initPath) : void 0;
@@ -734,16 +782,28 @@ function generateServerlessEntry(appPath, initPath) {
   lines.push(`export { handler };`);
   return lines.join("\n") + "\n";
 }
-async function buildServerless(args) {
+function generateRuntimeEntry(appPath, initPath) {
+  const absAppPath = (0, import_node_path.resolve)(process.cwd(), appPath);
+  const absInitPath = initPath ? (0, import_node_path.resolve)(process.cwd(), initPath) : void 0;
+  const lines = [
+    "// Auto-generated by @web-ts-toolkit/express-runtime CLI \u2014 do not edit.",
+    `import app from ${JSON.stringify(absAppPath)};`,
+    "export default app;",
+    "export { app };"
+  ];
+  if (absInitPath) {
+    lines.push(`export { default as init } from ${JSON.stringify(absInitPath)};`);
+  }
+  return lines.join("\n") + "\n";
+}
+async function buildBundle(args, tempEntryFilename, entryContent) {
   const tsupModule = await import("tsup");
   const { build } = tsupModule;
-  const entryContent = generateServerlessEntry(args.appPath, args.initPath);
-  const tempEntryPath = (0, import_node_path.resolve)(process.cwd(), TEMP_ENTRY_FILENAME);
+  const tempEntryPath = (0, import_node_path.resolve)(process.cwd(), tempEntryFilename);
   (0, import_node_fs.writeFileSync)(tempEntryPath, entryContent, "utf8");
   try {
     await build({
       config: false,
-      // Don't auto-load tsup.config.ts from cwd
       entry: { [args.outName]: tempEntryPath },
       format: [args.format],
       target: args.target,
@@ -758,6 +818,12 @@ async function buildServerless(args) {
     (0, import_node_fs.rmSync)(tempEntryPath, { force: true });
   }
 }
+async function buildRuntime(args) {
+  await buildBundle(args, TEMP_BUILD_ENTRY_FILENAME, generateRuntimeEntry(args.appPath, args.initPath));
+}
+async function buildServerless(args) {
+  await buildBundle(args, TEMP_SERVERLESS_ENTRY_FILENAME, generateServerlessEntry(args.appPath, args.initPath));
+}
 function collectBody(req) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -816,6 +882,25 @@ function createServerlessAdapterApp(handler) {
     }
   });
 }
+async function loadBuiltApp(appPath) {
+  const fullPath = (0, import_node_path.resolve)(process.cwd(), appPath);
+  const moduleUrl = (0, import_node_url.pathToFileURL)(fullPath).href;
+  const mod = await import(moduleUrl);
+  const exported = extractExport(mod);
+  if (!exported) {
+    throw new Error(
+      `Module "${appPath}" must default-export an Express app or export it as "app". Exports: ${Object.keys(mod).join(", ")}`
+    );
+  }
+  const init = mod.init;
+  if (init !== void 0 && typeof init !== "function") {
+    throw new Error(`Module "${appPath}" must export "init" as a function when present.`);
+  }
+  return {
+    app: await resolveExport(exported, appPath),
+    init
+  };
+}
 async function loadHandler(handlerPath) {
   const fullPath = (0, import_node_path.resolve)(process.cwd(), handlerPath);
   const moduleUrl = (0, import_node_url.pathToFileURL)(fullPath).href;
@@ -853,11 +938,21 @@ async function main() {
       loadEnvFiles(start.env);
     }
     await preloadModules(start.require);
-    const handler = await loadHandler(start.handlerPath);
+    const { app, init } = await loadBuiltApp(start.appPath);
+    startLocalServer(app, { ...start.options, init, exitAfterShutdown: true });
+  } else if (parsedArgs.subcommand === "build") {
+    await buildRuntime(parsedArgs.build);
+  } else if (parsedArgs.subcommand === "start-serverless") {
+    const { startServerless } = parsedArgs;
+    if (startServerless.env.length > 0) {
+      loadEnvFiles(startServerless.env);
+    }
+    await preloadModules(startServerless.require);
+    const handler = await loadHandler(startServerless.handlerPath);
     const app = createServerlessAdapterApp(handler);
-    startLocalServer(app, { ...start.options, exitAfterShutdown: true });
+    startLocalServer(app, { ...startServerless.options, exitAfterShutdown: true });
   } else {
-    await buildServerless(parsedArgs.build);
+    await buildServerless(parsedArgs.buildServerless);
   }
 }
 main().catch((error) => {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-runtime",
   "description": "Express app factory plus serverless handler and local dev server helpers",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-runtime",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "sideEffects": false,
   "keywords": [
     "express",