@web-ts-toolkit/express-runtime 0.8.0 → 0.9.0

package/README.md

@@ -103,6 +103,29 @@ For TypeScript app modules, run the CLI through `tsx`:
 npx tsx ./node_modules/@web-ts-toolkit/express-runtime/dist/cli.js dev ./src/app.ts
 ```
 
+#### CLI — dev with env, require, and watch
+
+`--env` loads `.env` files into `process.env` (existing vars are not
+overridden). `--require` preloads modules (e.g. `tsconfig-paths/register` for
+TS path aliases) before the app module is loaded. `--watch` forks a child
+process running the server and restarts it on file changes:
+
+```sh
+npx tsx ./node_modules/@web-ts-toolkit/express-runtime/dist/cli.js dev ./src/app.ts \
+  --env .env \
+  --require tsconfig-paths/register \
+  --watch ./src,./shared \
+  --ext ts,json
+```
+
+> `--env` parses `KEY=VALUE` lines (supports `export` prefix, quoted values,
+> `#` comments). For advanced dotenv features (multiline, variable expansion),
+> use `--require dotenv/config` instead.
+>
+> `--watch` uses Node 20+'s `fs.watch` with `{ recursive: true }` and forks the
+> same CLI as a child process. On file change, the child receives `SIGTERM`,
+> waits for it to exit, and respawns after the debounce delay (`--delay`).
+
 > The `dev` command evaluates arbitrary code from `<app-module>` in the current
 > process and inherits its privileges. Init logic (e.g. DB connections) should
 > be placed at the top level of your app module since `dev` does not expose an
@@ -147,7 +170,7 @@ serverless platform:
 
 ```sh
 npx wtt-express-runtime build ./src/app.ts --out-dir dist
-npx wtt-express-runtime start ./dist/handler.js --port 9000
+npx wtt-express-runtime start ./dist/handler.js --port 9000 --env .env
 ```
 
 The handler module must export a `handler` function (named or default) that
@@ -291,6 +314,11 @@ Omitting `<command>` defaults to `dev` for backward compatibility.
 | `--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)    |
+| `--watch <paths>`         | Comma-separated paths to watch for restart (repeatable; forks a child process)            |
+| `--ext <extensions>`      | Comma-separated extensions to watch (default: `ts,js,mjs,cjs,json`)                       |
+| `--delay <ms>`            | Debounce ms before restarting on change (default: `500`)                                  |
 
 #### build options
 
@@ -307,13 +335,15 @@ 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`)                           |
+| 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) |
 
 #### global options
 

package/cli.js

@@ -27,6 +27,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var import_node_url = require("url");
 var import_node_path = require("path");
 var import_node_fs = require("fs");
+var import_node_module = require("module");
+var import_node_child_process = require("child_process");
 
 // src/index.ts
 var import_node_http = __toESM(require("http"));
@@ -194,6 +196,7 @@ function startLocalServer(app, options = {}) {
 }
 
 // src/cli-utils.ts
+var import_meta = {};
 var CLI_VERSION = "0.0.0-PLACEHOLDER";
 function readValue(argv, index, name) {
   const value = argv[index + 1];
@@ -221,6 +224,11 @@ Dev options:
   --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)
+  --watch <paths>               Comma-separated paths to watch for restart (repeatable; dev only)
+  --ext <extensions>            Comma-separated extensions to watch (default: ts,js,mjs,cjs,json)
+  --delay <ms>                  Debounce ms before restarting on change (default: 500)
 
 Build options:
   --init <path>                 Init hook module (default export, async function)
@@ -236,6 +244,8 @@ Start options:
   --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)
+  --env <path>                  Env file(s) to load (repeatable; existing env vars are not overridden)
 
 Global options:
   -V, --version                 Show version
@@ -244,15 +254,21 @@ Global options:
 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
+  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
 
 Notes:
   - In dev mode, the CLI evaluates arbitrary code from <app-module> in the current process.
   - TypeScript app modules in dev mode require a TS loader. Run via tsx:
       npx tsx ./node_modules/@web-ts-toolkit/express-runtime/dist/cli.js dev ./src/app.ts
+    Or use --require with a TS-aware loader module.
+  - --env files are parsed as KEY=VALUE; existing process.env entries are never overridden.
+    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, tsup is required: pnpm add -D tsup
   - 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>.
@@ -268,8 +284,23 @@ function isHelp(arg) {
 function isSubcommand(arg) {
   return arg === "dev" || arg === "build" || arg === "start";
 }
+var DEFAULT_WATCH_EXTENSIONS = ["ts", "js", "mjs", "cjs", "json"];
+var DEFAULT_WATCH_DELAY = 500;
+function parseRepeatable(argv, index, arg, list) {
+  const value = readValue(argv, index, arg);
+  for (const part of value.split(",")) {
+    const trimmed = part.trim();
+    if (trimmed) list.push(trimmed);
+  }
+  return index + 1;
+}
 function parseDevArgs(argv) {
   const options = {};
+  const requireModules = [];
+  const envFiles = [];
+  const watchPaths = [];
+  let watchExt;
+  let watchDelay;
   let appPath;
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -314,6 +345,61 @@ function parseDevArgs(argv) {
       options.shutdownTimeout = Number(arg.slice("--shutdown-timeout=".length));
       continue;
     }
+    if (arg === "--require") {
+      index = parseRepeatable(argv, index, arg, requireModules);
+      continue;
+    }
+    if (arg.startsWith("--require=")) {
+      for (const part of arg.slice("--require=".length).split(",")) {
+        const trimmed = part.trim();
+        if (trimmed) requireModules.push(trimmed);
+      }
+      continue;
+    }
+    if (arg === "--env") {
+      index = parseRepeatable(argv, index, arg, envFiles);
+      continue;
+    }
+    if (arg.startsWith("--env=")) {
+      for (const part of arg.slice("--env=".length).split(",")) {
+        const trimmed = part.trim();
+        if (trimmed) envFiles.push(trimmed);
+      }
+      continue;
+    }
+    if (arg === "--watch") {
+      index = parseRepeatable(argv, index, arg, watchPaths);
+      continue;
+    }
+    if (arg.startsWith("--watch=")) {
+      for (const part of arg.slice("--watch=".length).split(",")) {
+        const trimmed = part.trim();
+        if (trimmed) watchPaths.push(trimmed);
+      }
+      continue;
+    }
+    if (arg === "--ext") {
+      watchExt = [];
+      index = parseRepeatable(argv, index, arg, watchExt);
+      continue;
+    }
+    if (arg.startsWith("--ext=")) {
+      watchExt = [];
+      for (const part of arg.slice("--ext=".length).split(",")) {
+        const trimmed = part.trim();
+        if (trimmed) watchExt.push(trimmed);
+      }
+      continue;
+    }
+    if (arg === "--delay") {
+      watchDelay = Number(readValue(argv, index, arg));
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--delay=")) {
+      watchDelay = Number(arg.slice("--delay=".length));
+      continue;
+    }
     if (!arg.startsWith("--")) {
       if (appPath) {
         throw new Error(`Unexpected positional argument: ${arg}. App module already set to ${appPath}`);
@@ -327,11 +413,29 @@ function parseDevArgs(argv) {
     printHelp();
     throw new Error("Missing required argument: <app-module>");
   }
-  return { appPath, options };
+  return {
+    appPath,
+    options,
+    require: requireModules,
+    env: envFiles,
+    watch: watchPaths,
+    watchExt: watchExt ?? DEFAULT_WATCH_EXTENSIONS,
+    watchDelay: watchDelay ?? DEFAULT_WATCH_DELAY
+  };
 }
 function parseStartArgs(argv) {
+  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`);
+    }
+  }
   const result = parseDevArgs(argv);
-  return { handlerPath: result.appPath, options: result.options };
+  return {
+    handlerPath: result.appPath,
+    options: result.options,
+    require: result.require,
+    env: result.env
+  };
 }
 function parseBuildArgs(argv) {
   let appPath;
@@ -494,6 +598,124 @@ async function loadApp(appPath) {
   }
   return resolveExport(exported, appPath);
 }
+function parseEnvFile(content) {
+  const result = {};
+  for (const line of content.split("\n")) {
+    let trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith("export ")) trimmed = trimmed.slice("export ".length).trim();
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) continue;
+    const key = trimmed.slice(0, eqIndex).trim();
+    let value = trimmed.slice(eqIndex + 1).trim();
+    if (value.length >= 2) {
+      const first = value[0];
+      const last = value[value.length - 1];
+      if (first === '"' && last === '"' || first === "'" && last === "'") {
+        value = value.slice(1, -1);
+      }
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function loadEnvFiles(paths) {
+  for (const p of paths) {
+    const absPath = (0, import_node_path.resolve)(process.cwd(), p);
+    if (!(0, import_node_fs.existsSync)(absPath)) {
+      throw new Error(`Env file not found: ${p}`);
+    }
+    const content = (0, import_node_fs.readFileSync)(absPath, "utf8");
+    const parsed = parseEnvFile(content);
+    for (const [key, value] of Object.entries(parsed)) {
+      if (process.env[key] === void 0) {
+        process.env[key] = value;
+      }
+    }
+  }
+}
+var moduleRequire = (0, import_node_module.createRequire)(
+  typeof import_meta !== "undefined" && import_meta.url || (0, import_node_path.resolve)(process.cwd(), "x").replace(/x$/, "")
+);
+async function preloadModules(modules) {
+  for (const mod of modules) {
+    moduleRequire(mod);
+  }
+}
+function buildChildArgs(args) {
+  const result = ["dev", args.appPath];
+  if (args.options.port !== void 0) result.push("--port", String(args.options.port));
+  if (args.options.host !== void 0) result.push("--host", args.options.host);
+  if (args.options.signals === false) result.push("--no-signals");
+  if (args.options.shutdownTimeout !== void 0)
+    result.push("--shutdown-timeout", String(args.options.shutdownTimeout));
+  for (const r of args.require) result.push("--require", r);
+  for (const e of args.env) result.push("--env", e);
+  return result;
+}
+function runWithWatch(args) {
+  const cliPath = process.argv[1];
+  const childArgv = buildChildArgs(args);
+  let child = null;
+  let restartTimer = null;
+  let isShuttingDown = false;
+  const restartDelay = args.watchDelay;
+  const spawnChild = () => {
+    child = (0, import_node_child_process.fork)(cliPath, childArgv, { stdio: "inherit" });
+    child.on("exit", (code) => {
+      child = null;
+      if (!isShuttingDown && code !== null && code !== 0) {
+      }
+    });
+  };
+  const killChild = () => {
+    return new Promise((resolve) => {
+      if (!child || !child.pid) {
+        resolve();
+        return;
+      }
+      child.once("exit", () => resolve());
+      child.kill("SIGTERM");
+    });
+  };
+  const restart = async () => {
+    await killChild();
+    spawnChild();
+  };
+  const debouncedRestart = () => {
+    if (restartTimer) clearTimeout(restartTimer);
+    restartTimer = setTimeout(() => {
+      restartTimer = null;
+      void restart();
+    }, restartDelay);
+  };
+  for (const watchPath of args.watch) {
+    const absPath = (0, import_node_path.resolve)(process.cwd(), watchPath);
+    if (!(0, import_node_fs.existsSync)(absPath)) {
+      throw new Error(`Watch path not found: ${watchPath}`);
+    }
+    (0, import_node_fs.watch)(absPath, { recursive: true }, (_eventType, filename) => {
+      if (!filename) return;
+      const ext = (0, import_node_path.extname)(filename).slice(1).toLowerCase();
+      if (args.watchExt.includes(ext)) {
+        debouncedRestart();
+      }
+    });
+  }
+  const shutdown = () => {
+    isShuttingDown = true;
+    if (restartTimer) clearTimeout(restartTimer);
+    if (child && child.pid) {
+      child.once("exit", () => process.exit(0));
+      child.kill("SIGTERM");
+    } else {
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  spawnChild();
+}
 var TEMP_ENTRY_FILENAME = ".express-runtime-build-entry.ts";
 function generateServerlessEntry(appPath, initPath) {
   const absAppPath = (0, import_node_path.resolve)(process.cwd(), appPath);
@@ -619,12 +841,26 @@ async function main() {
     return;
   }
   if (parsedArgs.subcommand === "dev") {
-    const app = await loadApp(parsedArgs.dev.appPath);
-    startLocalServer(app, { ...parsedArgs.dev.options, exitAfterShutdown: true });
+    const { dev } = parsedArgs;
+    if (dev.watch.length > 0) {
+      runWithWatch(dev);
+      return;
+    }
+    if (dev.env.length > 0) {
+      loadEnvFiles(dev.env);
+    }
+    await preloadModules(dev.require);
+    const app = await loadApp(dev.appPath);
+    startLocalServer(app, { ...dev.options, exitAfterShutdown: true });
   } else if (parsedArgs.subcommand === "start") {
-    const handler = await loadHandler(parsedArgs.start.handlerPath);
+    const { start } = parsedArgs;
+    if (start.env.length > 0) {
+      loadEnvFiles(start.env);
+    }
+    await preloadModules(start.require);
+    const handler = await loadHandler(start.handlerPath);
     const app = createServerlessAdapterApp(handler);
-    startLocalServer(app, { ...parsedArgs.start.options, exitAfterShutdown: true });
+    startLocalServer(app, { ...start.options, exitAfterShutdown: true });
   } else {
     await buildServerless(parsedArgs.build);
   }

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.8.0",
+  "version": "0.9.0",
   "sideEffects": false,
   "keywords": [
     "express",