express-generator-typescript 2.9.0 → 2.9.1

package/README.md

@@ -1,17 +1,198 @@
-<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)
+
+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).
+
+<p align="center">· · ·</p>
+
+## 🧭 Overview 
+
+`express-generator-typescript` creates a new Express application similar to the classic `express-generator` package, but the generated project is fully wired for TypeScript. You get strict typing, linting, hot reloading, production builds, testing utilities, and sane defaults that focus on APIs (no view engine or opinionated ORM). Path aliases are preconfigured through `tsconfig-paths` and `_moduleAliases`, so referencing modules stays clean even as the app grows.
+
+<p align="center">· · ·</p>
+
+## ✨ Features
+
+- **TypeScript-first** – strict compiler settings, linting, and sensible tsconfig defaults ready to go.
+- **API-centric** – no view engine or extra dependencies; ideal for SPAs, mobile backends, or services.
+- **Productivity tooling** – includes nodemon, ts-node, hot reload scripts, Vitest, ESLint, and production builds.
+- **Path aliases** – `@src/*` aliases configured in `tsconfig.json` (and `_moduleAliases` in `package.json` for production) so you can import modules cleanly.
+- **Keeps dependencies lean** – no bundled ORM or UI layers; only the essentials for Express + TS development.
+
+<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
+```
+
+Use `--use-yarn` if you prefer Yarn over npm. If you omit the project name, the generator creates `express-gen-ts`.
+
+<p align="center">· · ·</p>
+
+## 🖥️ CLI Options
+
+| Option            | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `project name`    | Folder to create. Defaults to `express-gen-ts` if omitted.                  |
+| `--use-yarn`      | Installs dependencies with Yarn instead of npm.                             |
+| `--force`         | Writes into the target folder even if it is not empty (existing files with the same names are overwritten). |
+| `-h`, `--help`    | Shows usage.                                                                |
+| `-v`, `--version` | Shows the generator version.                                                |
+
+> The generator refuses to 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 template is a CRUD app for the `User` record to demonstrate model, services, and routing patterns in Express + TypeScript. Commands for linting, transpiling, formatting, and hot-reloading are all configured for you.
+
+### Available `package.json` Scripts
+
+- `npm run dev` – Run the server in dev mode with live reload and browser refresh.
+- `npm run test` - Run tests with vitest.
+- `npm run test -- users.test.ts` – Target a single test file.
+- `npm run lint` – Run ESLint checks.
+- `npm run format` - Run prettier.
+- `npm run build` – Compile the project for production.
+- `npm start` – Serve the built project.
+- `npm run typecheck` – Run the TypeScript compiler without emitting files.
+- `npm run install:clean` – Delete `node_modules` and the lockfile, then reinstall.
+
+### Architecture
+
+Because this is a small CRUD app, **layered** is the architectural pattern of choice. However, you should consider switching to a **domain-based** layout if you plan on scaling. There is a good tutorial [here](https://github.com/seanpmaxwell/Typescript-Best-Practices/tree/main?tab=readme-ov-file#architecture) in the _Typescript Best Practices README_ about architectural patterns with TypeScript.
+
+Layers explained:
+```yml
+- src/ <-- source code
+  - common/
+    - constants/
+      - Paths.ts <-- Single source of truth for all API routes
+  - routes/ <-- extracting and validating values from express Request/Response objects
+  - services/ <-- Business logic (where everything comes together)
+  - repos/ <-- Talking to the database layer
+  - models/ <-- For describing/handling objects representing database records
+- tests/ <-- unit-tests
+```
+
+<p align="center">· · ·</p>
+
+## Notes for VSCode users
+
+<details>
+<summary>Format on save</summary>
+
+The generated template uses `eslint`+`prettier`, so if you want features like _formatting on save_, you need to make sure to install the prettier extension for VSCode and set it as your default formatter in `.vscode/setting.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>
+
+If you want to debug in VSCode with breakpoints you need to start the processes through `.vscode/launch.json`:
+
+```json
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Dev - ts-node",
+      "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/package.json

@@ -29,12 +29,11 @@
     "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",

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

@@ -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,5 @@
 import jetEnv, { num } from 'jet-env';
-import tspo from 'tspo';
+import { ValueOf } from '../types/utility-types';
 
 // ========================================================================= //
 //                                 CONSTANTS                                 //
@@ -11,18 +11,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/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';
 
 // ========================================================================= //

package/lib/template/src/repos/MockOrm.ts

@@ -2,7 +2,7 @@ import fs from 'fs/promises';
 import jsonfile from 'jsonfile';
 import path from 'path';
 
-import EnvVars, { NodeEnvs } from '@src/common/constants/env';
+import { EnvVars, NodeEnvs } from '@src/common/constants/env-inv';
 import { IUser } from '@src/models/User.model';
 
 // ========================================================================= //

package/lib/template/src/server.ts

@@ -9,7 +9,7 @@ import Paths from '@src/common/constants/Paths';
 import { RouteError } from '@src/common/utils/route-errors';
 import BaseRouter from '@src/routes/apiRouter';
 
-import EnvVars, { NodeEnvs } from './common/constants/env';
+import { EnvVars, NodeEnvs } from './common/constants/env-inv';
 
 // ========================================================================= //
 //                                   EXEC                                    //

package/package.json

@@ -1,15 +1,11 @@
 {
   "name": "express-generator-typescript",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "Generate new Express applications similar to express-generate which but sets it up to use TypeScript instead",
   "scripts": {
     "commit": "git add -A && git commit -m \"dev commit\"",
     "commit:push": "npm run commit && git push",
     "install:clean": "rm -rf node_modules && rm -rf package-lock.json && npm i",
-    "prepack": "npm run readme:swap",
-    "postpack": "npm run readme:restore",
-    "readme:swap": "node scripts/readme.js swap",
-    "readme:restore": "node scripts/readme.js restore",
     "test": "node --test \"tests/**/*.test.js\"",
     "test:e2e": "node scripts/e2e.js"
   },