express-generator-typescript 2.9.0 → 3.0.1

package/README.md

@@ -1,17 +1,196 @@
-<p align="center">
-  <img alt="express-generator-typescript" src="https://github.com/seanpmaxwell/express-generator-typescript/raw/main/assets/express-typescript.png" width="420">
-</p>
-
-# express-generator-typescript
-
-[![npm version](https://img.shields.io/npm/v/express-generator-typescript?logo=npm&label=npm)](https://www.npmjs.com/package/express-generator-typescript)
-[![npm downloads](https://img.shields.io/npm/dm/express-generator-typescript?color=orange)](https://www.npmjs.com/package/express-generator-typescript)
-[![License](https://img.shields.io/npm/l/express-generator-typescript)](https://github.com/seanpmaxwell/express-generator-typescript/blob/main/LICENSE)
-
-Command line tool which generates production-ready express templates with TypeScript baked in. Spin up a web server in seconds that follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices/blob/main/README.md).
-<br/>
-
-
-## Documenation
-
-Please refer to the official <a href="https://github.com/seanpmaxwell/express-generator-typescript">github repo</a> for the most up-to-date documentation.
+<p align="center">
+  <img alt="express-generator-typescript" src="https://github.com/seanpmaxwell/express-generator-typescript/raw/main/assets/express-typescript.png" width="420">
+</p>
+
+# express-generator-typescript
+
+[![npm version](https://img.shields.io/npm/v/express-generator-typescript?logo=npm&label=npm)](https://www.npmjs.com/package/express-generator-typescript)
+[![npm downloads](https://img.shields.io/npm/dm/express-generator-typescript?color=orange)](https://www.npmjs.com/package/express-generator-typescript)
+[![License](https://img.shields.io/npm/l/express-generator-typescript)](https://github.com/seanpmaxwell/express-generator-typescript/blob/main/LICENSE)
+
+A command-line tool that generates production-ready Express projects with TypeScript built in. Spin up a web server in seconds that follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices).
+
+<p align="center">· · ·</p>
+
+## 🧭 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.
+
+<p align="center">· · ·</p>
+
+## ✨ Features
+
+- **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.
+- **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.
+
+```bash
+npx express-generator-typescript
+# or install globally
+npm install -g express-generator-typescript
+```
+
+<p align="center">· · ·</p>
+
+## ⚡ Quick Start
+
+```bash
+# generate a project (defaults to express-gen-ts)
+npx express-generator-typescript my-api
+
+cd my-api
+
+# start developing at http://localhost:3000
+npm run dev
+```
+
+<p align="center">· · ·</p>
+
+## 🖥️ CLI Options
+
+| Option            | Description                                                        |
+| ----------------- | ------------------------------------------------------------------ |
+| `project name`    | Folder to create. Defaults to `express-gen-ts`.                    |
+| `--use-yarn`      | Install dependencies with Yarn instead of npm.                     |
+| `--force`         | Write into a folder that isn't empty. Files with the same name are overwritten. |
+| `-h`, `--help`    | Show usage.                                                        |
+| `-v`, `--version` | Show the generator version.                                        |
+
+> Without `--force`, the generator won't write into a folder that already has files in it, so it can't overwrite your work by accident.
+
+<p align="center">· · ·</p>
+
+## 🧩 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.
+
+### 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 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 run install:clean` – Delete `node_modules` and the lockfile, then reinstall.
+
+### Architecture
+
+The app uses a **layered** architecture, which suits a small CRUD app. If you plan to grow it, consider switching to a **domain-based** layout. The [Typescript Best Practices README](https://github.com/seanpmaxwell/Typescript-Best-Practices/tree/main?tab=readme-ov-file#architecture) explains both patterns.
+
+Layers explained:
+```yml
+- src/ <-- Source code
+  - common/
+    - constants/
+      - Paths.ts <-- Single source of truth for all API routes
+  - routes/ <-- Read and validate values from Express requests; send responses
+  - services/ <-- Business logic (where everything comes together)
+  - repos/ <-- Talk to the database
+  - models/ <-- Describe and handle database records
+- tests/ <-- Tests
+```
+
+<p align="center">· · ·</p>
+
+## Notes for VS Code users
+
+<details>
+<summary>Format on save</summary>
+
+The generated project uses ESLint for linting and Prettier for formatting. To format on save, install the Prettier extension for VS Code and set it as the default formatter in `.vscode/settings.json`:
+
+```json
+// .vscode/settings.json
+{
+  "editor.minimap.enabled": false,
+  "editor.rulers": [80],
+  "editor.tabSize": 2,
+
+  "workbench.sideBar.location": "right",
+  "workbench.editor.empty.hint": "hidden",
+
+  // Formatting: Prettier only
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+
+  // ESLint: linting only (NO formatting)
+  "eslint.format.enable": false,
+  "eslint.nodePath": "node_modules",
+  "eslint.validate": ["javascript", "typescript", "typescriptreact"],
+
+  // Run ESLint fixes (non-formatting) on save
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+
+  // Language overrides (keep Prettier)
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+
+  // JSDoc noise reduction
+  "javascript.suggest.completeJSDocs": false,
+  "javascript.suggest.jsdoc.generateReturns": false,
+  "typescript.suggest.completeJSDocs": false,
+  "typescript.suggest.jsdoc.generateReturns": false
+}
+```
+
+</details>
+
+<details>
+<summary>Debugging</summary>
+
+To debug with breakpoints in VS Code, start the app or tests from `.vscode/launch.json`:
+
+```json
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Dev",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "skipFiles": ["<node_internals>/**"],
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Test - Vitest",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "test"],
+      "skipFiles": ["<node_internals>/**"],
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+</details>
+
+<p align="center">· · ·</p>
+
+## 📄 License 
+
+MIT © [seanpmaxwell1](LICENSE)

package/lib/template/README.md

@@ -2,32 +2,29 @@
 
 This project was created with [express-generator-typescript](https://github.com/seanpmaxwell/express-generator-typescript). It requires Node.js 22.12 or newer.
 
-<p align="center">· · ·</p>
+The original template follows the [TypeScript best practices](https://github.com/seanpmaxwell/Typescript-Best-Practices).
 
+<p align="center">· · ·</p>
 
 ## Available Scripts
 
-### `npm run install:clean`
-
-Remove the existing `node_modules/` folder, `package-lock.json`, and reinstall all library modules.
-
-### `npm run dev` 
+### `npm run dev`
 
-Run the server in development with hot reloading and browser refresh (see `package.json` for all `npm run dev` variations)<br/>
+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`.
 
-**IMPORTANT** development mode uses `swc` for performance reasons which DOES NOT check for typescript errors. Run `npm run typecheck` to check for type errors. NOTE: you should use your IDE to prevent most type errors.
+> **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.
 
 ### `npm test`
 
-Run unit-tests with <a href="https://vitest.dev/guide/">vitest</a>.
+Run the tests with [Vitest](https://vitest.dev/guide/).
 
 ### `npm run lint`
 
-Check for linting errors.
+Check the code with ESLint.
 
 ### `npm run format`
 
-Format `src/` and `tests/` with prettier.
+Format `src/` and `tests/` with Prettier.
 
 ### `npm run build`
 
@@ -35,16 +32,37 @@ Build the project for production.
 
 ### `npm start`
 
-Run the production build (Must be built first).
+Run the production build. Run `npm run build` first.
 
 ### `npm run typecheck`
 
-Check for typescript errors.
+Check for TypeScript errors without building.
+
+### `npm run install:clean`
+
+Delete `node_modules/` and `package-lock.json`, then reinstall all dependencies.
 
 <p align="center">· · ·</p>
 
+## Tech Stack
+
+- **Language**: [TypeScript](https://www.typescriptlang.org/) (strict mode, ES modules)
+- **Web server framework**: [Express](https://expressjs.com/en/) (v5)
+- **Security headers**: [helmet](https://helmet.js.org/) (production only)
+- **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.*`, and [jet-env](https://github.com/seanpmaxwell/jet-env) validates them
+- **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)
+- **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/`)
+
+<p align="center">· · ·</p>
 
 ## Additional Notes
 
-- `config/.env.production` is listed in `.gitignore` so production secrets don't get committed. Keep it out of version control and provide its values through your deployment tooling.
-- The database is a JSON file (`src/repos/common/database.json`, or `dist/repos/common/database.json` in production) meant only for the demo. It's created automatically if missing and isn't safe for concurrent writes, so replace `src/repos/MockOrm.ts` with a real database before going to production.
+- `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.

package/lib/template/package.json

@@ -1,26 +1,21 @@
 {
   "name": "express-typescript-example",
-  "version": "0.1.0",
+  "version": "1.0.0",
+  "type": "module",
   "scripts": {
-    "build": "shx rm -rf dist && npm run lint && tsc --project tsconfig.prod.json && npm run build:copy-static",
+    "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:basic": "cross-env DOTENV_CONFIG_PATH=./config/.env.development ts-node ./src/main",
-    "dev:watch": "nodemon --exec \"npm run dev:basic\" --watch ./src --ext .ts",
-    "dev": "concurrently \"npm run dev:watch\" \"npm run sync\"",
+    "dev": "cross-env DOTENV_CONFIG_PATH=./config/.env.development tsx watch --import dotenv/config ./src/main.ts",
     "lint": "eslint .",
     "format": "prettier --write .",
-    "start": "cross-env DOTENV_CONFIG_PATH=./config/.env.production node -r dotenv/config -r module-alias/register ./dist/main.js",
-    "sync": "delay 1s && browser-sync start --config bs-config.js",
+    "start": "cross-env DOTENV_CONFIG_PATH=./config/.env.production node --import dotenv/config ./dist/main.js",
     "test": "cross-env NODE_ENV=test vitest",
     "typecheck": "tsc -b --noEmit"
   },
   "engines": {
     "node": ">=22.12.0"
   },
-  "_moduleAliases": {
-    "@src": "dist"
-  },
   "dependencies": {
     "cross-env": "^10.1.0",
     "dotenv": "^18.0.4",
@@ -29,40 +24,34 @@
     "jet-env": "^1.1.6",
     "jet-id": "^1.3.1",
     "jet-logger": "3.0.0",
-    "jet-paths": "^4.0.1",
+    "jet-paths": "^4.0.2",
     "jet-validators": "^2.3.1",
     "jsonfile": "^6.2.1",
-    "module-alias": "^2.3.4",
-    "morgan": "^1.12.1",
-    "tspo": "^1.0.7"
+    "morgan": "^1.12.1"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@swc/core": "^1.16.2",
     "@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/supertest": "^7.2.1",
-    "browser-sync": "^3.0.4",
-    "concurrently": "^10.0.5",
-    "delay-cli": "^3.0.0",
+    "connect-livereload": "^0.6.1",
     "eslint": "^10.11.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-n": "^18.3.0",
     "jiti": "^2.7.0",
-    "nodemon": "^3.1.14",
+    "livereload": "^0.10.3",
     "prettier": "^3.9.9",
     "shx": "^0.4.0",
     "supertest": "^7.3.0",
-    "ts-node": "^10.9.2",
-    "tsconfig-paths": "^4.2.0",
+    "tsc-alias": "^1.9.5",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.1",
     "vitest": "^5.0.2"
-  },
-  "allowScripts": {
-    "@swc/core@1.16.2": true
   }
 }

package/lib/template/src/common/{utils → classes}/route-errors.ts

@@ -1,4 +1,4 @@
-import { ParseError } from 'jet-validators/utils';
+import type { ParseError } from 'jet-validators/utils';
 
 import HttpStatusCodes from '@src/common/constants/HttpStatusCodes';
 

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

@@ -1,4 +1,4 @@
-import { ValueOf } from '../types/utility-types';
+import type { ValueOf } from '../types/utility-types';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
@@ -386,8 +386,13 @@ const HttpStatusCodes = {
 } as const;
 
 // ========================================================================= //
-//                                  EXPORT                                   //
+//                                   TYPES                                   //
 // ========================================================================= //
 
 type HttpStatusCodes = ValueOf<typeof HttpStatusCodes>;
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
 export default HttpStatusCodes;

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

@@ -1,5 +1,6 @@
 import jetEnv, { num } from 'jet-env';
-import tspo from 'tspo';
+
+import type { ValueOf } from '../types/utility-types';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
@@ -11,18 +12,21 @@ export const NodeEnvs = {
   TEST: 'test',
   PRODUCTION: 'production',
 } as const;
+export type NodeEnvs = ValueOf<typeof NodeEnvs>;
 
 // ========================================================================= //
 //                                   EXEC                                    //
 // ========================================================================= //
 
-const EnvVars = jetEnv({
-  NodeEnv: (v) => tspo.isValue(NodeEnvs, v),
+// Setup the is `NodeEnvs` validator
+const isNodeEnv = (() => {
+  const vals = Object.values(NodeEnvs);
+  const valsFin = vals.map((item) => item.toLowerCase());
+  const set = new Set(valsFin);
+  return (val: unknown): val is NodeEnvs => set.has(val as NodeEnvs);
+})();
+
+export const EnvVars = jetEnv({
+  NodeEnv: isNodeEnv,
   Port: num,
 });
-
-// ========================================================================= //
-//                                  EXPORT                                   //
-// ========================================================================= //
-
-export default EnvVars;

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

@@ -0,0 +1,25 @@
+import connectLiveReload from 'connect-livereload';
+import type { Express } from 'express';
+import livereload from 'livereload';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * Development only: refresh the browser when front-end files change, and
+ * after `tsx 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.
+ */
+export function setupLiveReload(app: Express, watchDirs: string[]): void {
+  const server = livereload.createServer();
+  server.watch(watchDirs);
+  // A new process means the backend just restarted; reload once the browser
+  // reconnects so it picks up the new server code.
+  server.server.once('connection', () => {
+    setTimeout(() => server.refresh('/'), 100);
+  });
+  app.use(connectLiveReload());
+}

package/lib/template/src/entities/User/_internal/validators.ts

@@ -0,0 +1,47 @@
+import jetid from 'jet-id';
+import { isNonEmptyString, isString } from 'jet-validators';
+import { parseObject, type Schema, testObject } from 'jet-validators/utils';
+
+import { isISOString } from '@src/common/utils/date-utils';
+
+import type { UserEntity, UserInput } from '../types';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+const schema: Schema<UserEntity> = {
+  id: isUserId,
+  name: isString,
+  email: isString,
+  created: isISOString,
+};
+
+/**
+ * Validate the `User` schema.
+ */
+export const parseUser = parseObject<UserEntity>(schema);
+
+/**
+ * For the APIs make sure the right fields are complete
+ */
+export const isCompleteUser = testObject<UserEntity>({
+  ...schema,
+  name: isNonEmptyString,
+  email: isNonEmptyString,
+});
+
+/**
+ * Validate the fields a client sends to create a user.
+ */
+export const isUserInput = testObject<UserInput>({
+  name: isNonEmptyString,
+  email: isNonEmptyString,
+});
+
+/**
+ * Test if an id is a valid user id.
+ */
+export function isUserId(val: unknown): val is string {
+  return jetid.test(val);
+}

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

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

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

@@ -0,0 +1,63 @@
+import jetid from 'jet-id';
+
+import { getISOString, type ISOString } from '@src/common/utils/date-utils';
+
+import {
+  isCompleteUser,
+  isUserId,
+  isUserInput,
+  parseUser,
+} from './_internal/validators';
+import type { UserEntity } from './types';
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * Get a new `UserEntity` object with default values.
+ */
+function getDefaults(): UserEntity {
+  return {
+    id: jetid(),
+    name: '',
+    email: '',
+    created: getISOString(),
+  };
+}
+
+/**
+ * Factory-function.
+ *
+ * Create a `UserEntity` from a partial or `undefined`
+ */
+function create(user?: Partial<UserEntity>): UserEntity {
+  return parseUser({ ...getDefaults(), ...user }, (errors) => {
+    throw new Error('Setup new user failed ' + JSON.stringify(errors, null, 2));
+  });
+}
+
+/**
+ * Factory-function.
+ *
+ * Create a `UserEntity` from individual properties
+ */
+function of(name: string, email?: string, created?: ISOString): UserEntity {
+  const retVal = getDefaults();
+  if (name) retVal.name = name;
+  if (email) retVal.email = email;
+  if (created) retVal.created = created;
+  return retVal;
+}
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+export default {
+  of,
+  create,
+  isId: isUserId,
+  isComplete: isCompleteUser,
+  isInput: isUserInput,
+} as const;

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

@@ -0,0 +1,18 @@
+import type { Entity } from '@src/entities/common/types';
+
+// ========================================================================= //
+//                                   TYPES                                   //
+// ========================================================================= //
+
+/**
+ * @entity `users`
+ */
+export interface UserEntity extends Entity {
+  name: string;
+  email: string;
+}
+
+/**
+ * Fields a client supplies when creating a user; the server sets the rest.
+ */
+export type UserInput = Pick<UserEntity, 'name' | 'email'>;

package/lib/template/src/{models → entities}/common/types.ts

@@ -1,4 +1,4 @@
-import { ISOString } from "@src/common/utils/date-utils";
+import type { ISOString } from '@src/common/utils/date-utils';
 
 // ========================================================================= //
 //                                   TYPES                                   //

package/lib/template/src/main.ts

@@ -1,6 +1,6 @@
 import logger from 'jet-logger';
 
-import EnvVars from './common/constants/env';
+import { EnvVars } from './common/constants/env-inv';
 import server from './server';
 
 // ========================================================================= //