express-generator-typescript 3.0.4 → 3.2.0

package/README.md

@@ -14,7 +14,7 @@ A command-line tool that generates production-ready Express projects with TypeSc
 
 ## 🧭 Overview 
 
-`express-generator-typescript` works like the classic `express-generator` package, but the project it creates is fully set up for TypeScript. You get strict typing, linting, hot reloading, testing, and production builds, with defaults aimed at APIs. The project is an ES module and comes with an `@src/*` import alias, so imports stay clean as the app grows.
+`express-generator-typescript` works like the classic `express-generator` package, but the project it creates is fully set up for TypeScript. You get strict typing, linting, hot reloading, and testing, with defaults aimed at APIs and no build step. The project is an ES module and comes with a `#src/*` import alias, so imports stay clean as the app grows.
 
 <p align="center">· · ·</p>
 
@@ -22,15 +22,15 @@ A command-line tool that generates production-ready Express projects with TypeSc
 
 - **TypeScript-first** – strict compiler settings, linting, and sensible tsconfig defaults, ready to go.
 - **Built for APIs** – ideal for SPAs, mobile backends, or services.
-- **Fast development** – runs TypeScript directly with tsx (no build step), restarts the server when you change it, and refreshes the browser when you change front-end files. Vitest, ESLint, and production builds are included.
-- **Path aliases** – import from `@src/*` anywhere. It works in development, tests, and production builds.
+- **Fast development** – runs TypeScript directly with Node's built-in type stripping (no build step, in development or production), restarts the server when you change it, and refreshes the browser when you change front-end files. Node's built-in test runner and ESLint are included.
+- **Path aliases** – import from `#src/*` anywhere. It works in development, tests, and production.
 - **Lean dependencies** – no view engine, ORM, or UI layer; only the essentials for Express + TypeScript.
 
 <p align="center">· · ·</p>
 
 ## 📦 Installation
 
-Requires Node.js 22.12 or newer.
+Requires Node.js 22.18+ (22.x), 24.x, or 26+.
 
 ```bash
 npx express-generator-typescript
@@ -70,20 +70,19 @@ npm run dev
 
 ## 🧩 Generated Template
 
-The generated project is a small CRUD app for a `User` record. It shows how to structure models, services, and routes in Express + TypeScript. Linting, formatting, building, and hot reloading are all set up for you.
+The generated project is a small CRUD app for a `User` record. It shows how to structure models, services, and routes in Express + TypeScript. Linting, formatting, testing, and hot reloading are all set up for you.
 
 ---
 
 #### Available `package.json` scripts
 
 - `npm run dev` – Run the server in development with live reload and browser refresh.
-- `npm test` – Run the tests with Vitest.
-- `npm test -- users.test.ts` – Run a single test file.
+- `npm test` – Run the tests with Node's built-in test runner.
+- `npm test -- tests/users.test.ts` – Run a single test file.
 - `npm run lint` – Check the code with ESLint.
 - `npm run format` – Format the code with Prettier.
-- `npm run build` – Build the project for production.
-- `npm start` – Run the production build.
-- `npm run typecheck` – Check for TypeScript errors without building.
+- `npm start` – Run the server in production mode (no build step).
+- `npm run typecheck` – Check for TypeScript errors.
 - `npm run install:clean` – Delete `node_modules` and the lockfile, then reinstall.
 
 ---
@@ -187,7 +186,7 @@ To debug with breakpoints in VS Code, start the app or tests from `.vscode/launc
       "console": "integratedTerminal"
     },
     {
-      "name": "Test - Vitest",
+      "name": "Test",
       "type": "node",
       "request": "launch",
       "runtimeExecutable": "npm",

package/bin/cli.js

@@ -3,14 +3,13 @@ const path = require('path');
 const { parseArgs } = require('util');
 
 const expressGenTs = require('../lib/express-generator-typescript');
-const { version, engines } = require('../package.json');
+const { version } = require('../package.json');
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
 // ========================================================================= //
 
 const DEFAULT_DEST = 'express-gen-ts';
-const MIN_NODE = engines.node.replace(/^>=/, '');
 
 const HELP = `Usage: express-generator-typescript [project-name] [options]
 
@@ -62,7 +61,6 @@ async function main() {
   if (positionals.length > 1) {
     throw new Error('Expected at most one project name.\n\n' + HELP);
   }
-  assertNodeVersion();
 
   // ---- Run "express-generator-typescript"
   const dest = path.resolve(process.cwd(), positionals[0] ?? DEFAULT_DEST);
@@ -73,20 +71,3 @@ async function main() {
   });
   console.log('Project setup complete!');
 }
-
-/**
- * The generated project's tooling (vitest, eslint) requires a recent Node, so
- * fail fast instead of producing a project that can't run.
- *
- * @returns {void}
- */
-function assertNodeVersion() {
-  const toParts = (v) => v.split('.').map(Number);
-  const [maj, min] = toParts(process.versions.node);
-  const [reqMaj, reqMin] = toParts(MIN_NODE);
-  if (maj < reqMaj || (maj === reqMaj && min < reqMin)) {
-    throw new Error(
-      `Node ${MIN_NODE} or newer is required (found ${process.versions.node}).`,
-    );
-  }
-}

package/lib/template/.prettierrc.json

@@ -2,7 +2,7 @@
   "plugins": ["@trivago/prettier-plugin-sort-imports"],
   "importOrder": [
     "<THIRD_PARTY_MODULES>",
-    "^@src/[^/]+(/.*)?$",
+    "^#src/[^/]+(/.*)?$",
     "^\\.(?!.*\\.css$).*$",
     "^.+\\.css$"
   ],

package/lib/template/README.md

@@ -1,6 +1,6 @@
 ## About
 
-This project was created with [express-generator-typescript](https://github.com/seanpmaxwell/express-generator-typescript). It requires Node.js 22.12 or newer.
+This project was created with [express-generator-typescript](https://github.com/seanpmaxwell/express-generator-typescript). It requires Node.js 22.18+ (22.x), 24.x, or 26+.
 
 The original template follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices).
 
@@ -12,11 +12,11 @@ The original template follows the [TypeScript best practices](https://github.com
 
 Run the server in development at http://localhost:3000. The server restarts when you change server code, and the browser refreshes when you change server code or anything in `src/public` or `src/views`.
 
-> **Note:** development mode runs your `.ts` files directly with `tsx`, which doesn't check for TypeScript errors. Run `npm run typecheck` to check for them, and let your editor catch most of them as you work.
+> **Note:** Node runs your `.ts` files directly with Node's built-in [type stripping](https://nodejs.org/api/typescript.html), which doesn't check for TypeScript errors. Run `npm run typecheck` to check for them, and let your editor catch most of them as you work.
 
 ### `npm test`
 
-Run the tests with [Vitest](https://vitest.dev/guide/).
+Run the tests with Node's built-in [test runner](https://nodejs.org/api/test.html). Pass a file to run only that file (`npm test -- tests/users.test.ts`), or `--test-name-pattern` to run only matching tests (`npm test -- --test-name-pattern="UserRouter"`).
 
 ### `npm run lint`
 
@@ -26,17 +26,13 @@ Check the code with ESLint.
 
 Format `src/` and `tests/` with Prettier.
 
-### `npm run build`
-
-Build the project for production.
-
 ### `npm start`
 
-Run the production build. Run `npm run build` first.
+Run the server in production mode. There's no build step: like `npm run dev`, this runs the `.ts` files in `src/` directly, so run `npm run typecheck` and `npm run lint` before you deploy.
 
 ### `npm run typecheck`
 
-Check for TypeScript errors without building.
+Check for TypeScript errors.
 
 ### `npm run install:clean`
 
@@ -52,17 +48,19 @@ Delete `node_modules/` and `package-lock.json`, then reinstall all dependencies.
 - **Logging**
   - **Request logging**: [morgan](https://github.com/expressjs/morgan) (development only)
   - **General logging**: [jet-logger](https://github.com/seanpmaxwell/jet-logger)
-- **Validation**: [jet-validators](https://github.com/seanpmaxwell/jet-validators)
-- **Environment variables**: [dotenv](https://github.com/motdotla/dotenv) loads `config/.env.*`
-- **Reloading**: [tsx](https://tsx.hirok.io) (`tsx watch` restarts the server) and [livereload](https://github.com/napcs/node-livereload) + [connect-livereload](https://github.com/intesso/connect-livereload) (refreshes the browser)
-- **Testing**: [Vitest](https://vitest.dev) + [Supertest](https://github.com/ladjs/supertest)
+- **Validation**: [zod](https://github.com/colinhacks/zod)
+  - **Middleware Validation**: [express-zod-safe](https://github.com/AngaBlue/express-zod-safe)
+- **Environment variables**: Node's built-in [`--env-file`](https://nodejs.org/api/cli.html#--env-fileconfig) loads `config/.env.*`
+- **Reloading**: Node's built-in [`--watch`](https://nodejs.org/api/cli.html#--watch) (restarts the server) and [livereload](https://github.com/napcs/node-livereload) + [connect-livereload](https://github.com/intesso/connect-livereload) (refreshes the browser)
+- **Testing**: Node's built-in [`node:test`](https://nodejs.org/api/test.html) + [Supertest](https://github.com/ladjs/supertest)
 - **Linting**: [ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io/packages/typescript-eslint) and [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n)
 - **Formatting**: [Prettier](https://prettier.io) with [@trivago/prettier-plugin-sort-imports](https://github.com/trivago/prettier-plugin-sort-imports)
-- **Building**: `tsc` + [tsc-alias](https://github.com/justkey007/tsc-alias) (rewrites `@src/*` imports in `dist/`)
+- **Type checking**: `tsc` (`npm run typecheck`). There's no build step.
 
 <p align="center">· · ·</p>
 
 ## Additional Notes
 
+- Imports name the `.ts` file (`./server.ts`), because Node runs the source files directly. `#src/*` imports are [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) set up in `package.json` that point at `src/*`.
 - `config/.env.production` is in `.gitignore` so production secrets don't get committed. Keep it out of version control and supply its values through your deployment tooling.
-- The database is a JSON file meant only for the demo: `src/repos/common/database.json` in development, or `dist/repos/common/database.json` in production. It's created automatically if missing, but it isn't safe for simultaneous writes. Replace `src/repos/MockOrm.ts` with a real database before going to production.
+- The database is a JSON file meant only for the demo: `src/repos/common/database.json`. It's created automatically if missing, but it isn't safe for simultaneous writes. Replace `src/repos/MockOrm.ts` with a real database before going to production.

package/lib/template/eslint.config.ts

@@ -10,7 +10,7 @@ import tseslint from 'typescript-eslint';
 
 export default defineConfig([
   // global ignores
-  globalIgnores(['**/dist/**', '**/public/**/lib/**']),
+  globalIgnores(['**/public/**/lib/**']),
   // linting rules (code quality only)
   {
     files: ['**/*.{ts,tsx}'],
@@ -38,6 +38,15 @@ export default defineConfig([
           ignoreRestSiblings: true,
         },
       ],
+      // node:test's `describe`/`it` return promises the runner already tracks
+      '@typescript-eslint/no-floating-promises': [
+        'error',
+        {
+          allowForKnownSafeCalls: [
+            { from: 'package', name: ['describe', 'it'], package: 'node:test' },
+          ],
+        },
+      ],
       'no-console': 'warn',
       'no-extra-boolean-cast': 'off',
       'no-process-env': 'warn',

package/lib/template/gitignore

@@ -1,5 +1,4 @@
 **/node_modules
-dist/
 **/**/*.log
 tsconfig.tsbuildinfo
 

package/lib/template/package.json

@@ -3,57 +3,47 @@
   "version": "1.0.0",
   "type": "module",
   "scripts": {
-    "build": "shx rm -rf dist && npm run lint && tsc --project tsconfig.prod.json && tsc-alias -p tsconfig.prod.json && npm run build:copy-static",
-    "build:copy-static": "shx mkdir -p dist/public dist/views && shx cp -r src/public/* dist/public && shx cp -r src/views/* dist/views",
-    "install:clean": "shx rm -rf ./node_modules package-lock.json && npm i",
-    "dev": "cross-env DOTENV_CONFIG_PATH=./config/.env.development tsx watch --import dotenv/config ./src/main.ts",
+    "install:clean": "node -e \"fs.rmSync('node_modules', { recursive: true, force: true }); fs.rmSync('package-lock.json', { force: true })\" && npm i",
+    "dev": "node --env-file=config/.env.development --watch src/main.ts",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "start": "cross-env DOTENV_CONFIG_PATH=./config/.env.production node --import dotenv/config ./dist/main.js",
-    "test": "cross-env NODE_ENV=test vitest",
+    "start": "node --env-file-if-exists=config/.env.production src/main.ts",
+    "test": "node --env-file=config/.env.test --test --test-concurrency=1",
     "typecheck": "tsc -b --noEmit"
   },
+  "imports": {
+    "#src/*": "./src/*"
+  },
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^22.18.0 || ^24.0.0 || >=26.0.0"
   },
   "dependencies": {
-    "cross-env": "^10.1.0",
-    "dotenv": "^18.0.4",
-    "express": "^5.2.1",
+    "express": "^5.3.0",
+    "express-zod-safe": "^3.2.1",
     "helmet": "^8.3.0",
-    "jet-id": "^1.3.1",
     "jet-logger": "3.0.0",
-    "jet-paths": "^4.1.3",
-    "jet-validators": "^2.3.1",
-    "jsonfile": "^6.2.1",
-    "morgan": "^1.12.1"
+    "morgan": "^1.12.1",
+    "uuid": "^14.0.3",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/connect-livereload": "^0.6.3",
     "@types/express": "^5.0.6",
-    "@types/jsonfile": "^6.1.4",
     "@types/livereload": "^0.9.5",
     "@types/morgan": "^1.9.10",
-    "@types/node": "^26.6.2",
+    "@types/node": "^26.6.5",
     "@types/supertest": "^7.2.1",
     "connect-livereload": "^0.6.1",
-    "eslint": "^10.11.0",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-n": "^18.3.0",
+    "eslint-plugin-n": "^18.4.1",
     "jiti": "^2.7.0",
     "livereload": "^0.10.3",
-    "prettier": "^3.9.9",
-    "shx": "^0.4.0",
-    "supertest": "^7.3.0",
-    "tsc-alias": "^1.9.5",
-    "tsx": "^4.23.15",
+    "prettier": "^3.9.10",
+    "supertest": "^7.3.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.1",
-    "vitest": "^5.0.2"
-  },
-  "allowScripts": {
-    "esbuild@0.28.2": true
+    "typescript-eslint": "^8.71.1"
   }
 }

package/lib/template/src/common/classes/route-errors.ts

@@ -1,6 +1,4 @@
-import type { ParseError } from 'jet-validators/utils';
-
-import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
+import HttpStatusCodes from '#src/common/constants/HttpStatusCodes.ts';
 
 // ========================================================================= //
 //                                  CLASSES                                  //
@@ -33,14 +31,3 @@ export class NotFoundError extends RouteError {
     super(HttpStatusCodes.NOT_FOUND, message);
   }
 }
-
-/**
- * Request data failed schema validation.
- */
-export class ValidationError extends RouteError {
-  public static MESSAGE = 'Request validation failed.';
-
-  public constructor(errors: ParseError[]) {
-    super(HttpStatusCodes.BAD_REQUEST, ValidationError.MESSAGE, errors);
-  }
-}

package/lib/template/src/common/constants/HttpStatusCodes.ts

@@ -1,4 +1,4 @@
-import type { ValueOf } from '../utils/validators';
+import type { ValueOf } from '../utils/validators.ts';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //

package/lib/template/src/common/constants/Paths/Paths.ts

@@ -0,0 +1,29 @@
+import { ep, pp } from './helpers.ts';
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+const BASE = '/api';
+const USERS_BASE = '/users';
+const USERS = BASE + USERS_BASE;
+
+const Paths = {
+  PATH: BASE,
+  Users: {
+    PATH: USERS_BASE,
+    Get: ep(USERS, '/all', 'GET'),
+    Add: ep(USERS, '/add', 'POST'),
+    Update: ep(USERS, '/update', 'PUT'),
+    Delete: {
+      ...ep(USERS, `/delete/:id`, 'DELETE'),
+      format: (id: string) => `${USERS}/delete/${pp(id)}`,
+    },
+  },
+} as const;
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default Paths;

package/lib/template/src/common/constants/Paths/helpers.ts

@@ -0,0 +1,29 @@
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+type HttpVerb = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * `ep` stands for "Endpoint"
+ */
+export function ep<V extends HttpVerb>(base: string, path: string, verb: V) {
+  const template = `${base}${path}`;
+  return {
+    PATH: path,
+    FULL_PATH: template,
+    VERB: verb,
+    DISPLAY: `<${verb}>${template}`,
+  } as const;
+}
+
+/**
+ * `pp` stands for path params
+ */
+export function pp(param: string | number | boolean): string {
+  return encodeURIComponent(param);
+}

package/lib/template/src/common/constants/Paths/index.ts

@@ -0,0 +1 @@
+export { default as default } from './Paths.ts';

package/lib/template/src/common/constants/{environment-consts.ts → env.constants.ts}

@@ -1,7 +1,6 @@
 /* eslint-disable no-process-env */
 import logger from 'jet-logger';
-
-import { isNumber, isValueOf, type ValueOf } from '../utils/validators';
+import { z } from 'zod';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
@@ -13,9 +12,9 @@ export const NodeEnvs = {
   TEST: 'test',
   PRODUCTION: 'production',
 } as const;
-export type NodeEnvs = ValueOf<typeof NodeEnvs>;
+export type NodeEnvs = z.infer<typeof NodeEnvsEnum>;
 
-export const EnvVars = {
+export const Env = {
   NODE_ENV: process.env.NODE_ENV?.toLowerCase(),
   PORT: Number(process.env.PORT),
 } as const;
@@ -24,19 +23,18 @@ export const EnvVars = {
 //                                   EXEC                                    //
 // ========================================================================= //
 
-// ---- Validation
-// Validate the "environment variables"
+const NodeEnvsEnum = z.enum(NodeEnvs, 'Not a valid node environment');
+
+const EnvSchema = z.object({
+  NODE_ENV: NodeEnvsEnum,
+  PORT: z.uint32('Express port must be a positive integer'),
+});
+
+// ===================== Validate Environment Variables ==================== //
+
 {
   try {
-    const isNodeEnv = isValueOf(NodeEnvs);
-    if (!isNodeEnv(EnvVars.NODE_ENV)) {
-      throw new Error(
-        'process.env.NODE_ENV must be "development", "test", or "production"',
-      );
-    }
-    if (!isNumber(EnvVars.PORT)) {
-      throw new Error('process.env.PORT must be a valid number');
-    }
+    EnvSchema.parse(Env);
   } catch (err) {
     logger.err(err);
     throw err;

package/lib/template/src/common/utils/{date-utils.ts → date.utils.ts}

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 // ========================================================================= //
 //                                   TYPES                                   //
 // ========================================================================= //
@@ -5,6 +7,14 @@
 export type ISOString =
   `${number}-${number}-${number}T${number}:${number}:${number}${string}`;
 
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+export const ISOStringSchema = z.iso
+  .datetime()
+  .transform((value) => value as ISOString);
+
 // ========================================================================= //
 //                                 FUNCTIONS                                 //
 // ========================================================================= //
@@ -15,15 +25,3 @@ export type ISOString =
 export function getISOString(date = new Date()): ISOString {
   return date.toISOString() as ISOString;
 }
-
-/**
- * Validate an ISOString.
- */
-export function isISOString(value: unknown): value is ISOString {
-  try {
-    const date = new Date(value as string);
-    return !isNaN(date.getTime()) && date.toISOString() === value;
-  } catch {
-    return false;
-  }
-}

package/lib/template/src/common/utils/dev-only.ts

@@ -8,7 +8,7 @@ import livereload from 'livereload';
 
 /**
  * Development only: refresh the browser when front-end files change, and
- * after `tsx watch` restarts the server for a TypeScript change.
+ * after `node --watch` restarts the server for a TypeScript change.
  *
  * Must be registered before the routes that serve html so the reload script
  * gets injected into those pages.

package/lib/template/src/common/utils/validators.ts

@@ -3,26 +3,3 @@
 // ========================================================================= //
 
 export type ValueOf<T> = T[keyof T];
-type Table = Record<string, string> | Record<string, number>;
-
-// ========================================================================= //
-//                                   EXEC                                    //
-// ========================================================================= //
-
-/**
- * Check if an `unknown` is a number type.
- */
-export function isNumber<T>(val: T): val is Extract<T, number> {
-  return typeof val === 'number' && !isNaN(val);
-}
-
-/**
- * Check if an `unknown` is a value of an object.
- */
-export function isValueOf<T extends Table>(
-  table: T,
-): (v: unknown) => v is ValueOf<T> {
-  const vals = Object.values(table);
-  const set = new Set(vals);
-  return (val: unknown): val is ValueOf<T> => set.has(val);
-}

package/lib/template/src/entities/User/index.ts

@@ -1,2 +1,2 @@
-export { default as default } from './module';
-export type { UserEntity, UserInput } from './types';
+export { default as default } from './module.ts';
+export type { UserEntity, UserInput } from './types.ts';