express-generator-typescript 2.8.1 → 2.9.1

package/README.md

@@ -1,18 +1,198 @@
-<p align="center">
-  <img alt="express-generator-typescript" src="https://github.com/seanpmaxwell/express-generator-typescript/raw/master/express-typescript.png" width="420">
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/express-generator-typescript"><img src="https://img.shields.io/npm/v/express-generator-typescript.svg?style=for-the-badge&logo=npm" alt="NPM Version"></a>
-  <a href="https://www.npmjs.com/package/express-generator-typescript"><img src="https://img.shields.io/npm/dm/express-generator-typescript.svg?style=for-the-badge" alt="NPM Downloads"></a>
-  <a href="https://www.npmjs.com/package/express-generator-typescript"><img src="https://img.shields.io/npm/l/express-generator-typescript.svg?style=for-the-badge" alt="License"></a>
-</p>
-
-# express-generator-typescript
-
-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).
-
-
-## 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/bin/cli.js

@@ -1,33 +1,92 @@
 #!/usr/bin/env node
-
-const path = require('path'),
-  expressGenTs = require('../lib/express-generator-typescript');
-
-
-/******************************************************************************
-                              Run
-******************************************************************************/
-
-// Init
-console.log('Setting up new Express/TypeScript project...');
-const args = process.argv.slice(2);
-
-// Setup use yarn
-let useYarn = false;
-const useYarnIdx = args.indexOf('--use-yarn');
-if (useYarnIdx > -1) {
-  useYarn = true;
-  args.splice(useYarnIdx, 1);
-}
-
-// Setup destination
-let destination = 'express-gen-ts';
-if (args.length > 0) {
-  destination = args[0];
-}
-destination = path.join(process.cwd(), destination);
-
-// Creating new project finished
-expressGenTs(destination, useYarn).then(() => {
-  console.log('Project setup complete!');
-});
+const path = require('path');
+const { parseArgs } = require('util');
+
+const expressGenTs = require('../lib/express-generator-typescript');
+const { version, engines } = 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]
+
+Creates a new Express + TypeScript project (default name: "${DEFAULT_DEST}").
+
+Options:
+  --use-yarn     Install dependencies with yarn instead of npm
+  --force        Write into the target folder even if it is not empty
+  -h, --help     Show this help
+  -v, --version  Show the version`;
+
+// ========================================================================= //
+//                                   EXEC                                    //
+// ========================================================================= //
+
+main().catch((err) => {
+  console.error('\nProject setup failed: ' + err.message);
+  process.exitCode = 1;
+});
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * Parse the command-line args and hand off to `expressGenTs`.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  // ---- Parse command-line-arguments
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      'use-yarn': { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h', default: false },
+      version: { type: 'boolean', short: 'v', default: false },
+    },
+  });
+  if (values.help) {
+    console.log(HELP);
+    return;
+  }
+  if (values.version) {
+    console.log(version);
+    return;
+  }
+  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);
+  console.log('Setting up new Express/TypeScript project in ' + dest);
+  await expressGenTs(dest, {
+    useYarn: values['use-yarn'],
+    force: values.force,
+  });
+  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/express-generator-typescript.js

@@ -1,151 +1,125 @@
-const path = require('path'),
-  editJsonFile = require('edit-json-file'),
-  childProcess = require('child_process'),
-  ncp = require('ncp').ncp,
-  fs = require('fs');
-
-/******************************************************************************
-                                 Constants
-******************************************************************************/
-
-const PROJECT_FOLDER_PATH = './project-files';
-
-const DEPENDENCIES = [
-  'cookie-parser',
-  'cross-env',
-  'dayjs',
-  'dotenv',
-  'express',
-  'helmet',
-  'jet-env',
-  'jet-logger',
-  'jet-paths',
-  'jet-validators',
-  'jsonfile',
-  'module-alias',
-  'morgan',
-  'tspo',
-];
-
-const DEV_DEPENDENCIES = [
-  '@eslint/js',
-  '@swc/core',
-  '@trivago/prettier-plugin-sort-imports',
-  '@types/cookie-parser',
-  '@types/find',
-  '@types/fs-extra',
-  '@types/jsonfile',
-  '@types/module-alias',
-  '@types/morgan',
-  '@types/node',
-  '@types/supertest',
-  'browser-sync',
-  'concurrently',
-  'delay-cli',
-  'eslint',
-  'eslint-config-prettier',
-  'eslint-plugin-n',
-  'find',
-  'fs-extra',
-  'jiti',
-  'nodemon',
-  'prettier',
-  'shx',
-  'supertest',
-  'ts-node',
-  'tsconfig-paths',
-  'typescript',
-  'typescript-eslint',
-  'vitest',
-];
-
-// "ncp" options
-const ncpOpts = {
-  filter: (fileName) => {
-    return !(fileName === 'package-lock.json' || fileName === 'node_modules');
-  },
-};
-
-/******************************************************************************
-                                 Functions
-******************************************************************************/
-
-/**
- * Entry point
- */
-async function expressGenTs(destination, useYarn) {
-  try {
-    await copyProjectFiles(destination);
-    updatePackageJson(destination);
-    await renameGitigoreFile(destination);
-    downloadNodeModules(destination, useYarn);
-  } catch (err) {
-    console.error(err);
-  }
-}
-
-/**
- * Copy project files
- */
-function copyProjectFiles(destination) {
-  const source = path.join(__dirname, PROJECT_FOLDER_PATH);
-  return /** @type {Promise<void>} */(new Promise((res, rej) => {
-    return ncp(source, destination, ncpOpts, (err) => {
-      return (!!err ? rej(err) : res());
-    });
-  }));
-}
-
-/**
- * Set update the package.json file.
- */
-function updatePackageJson(destination) {
-  let file = editJsonFile(destination + '/package.json', {
-    autosave: true
-  });
-  file.set('name', path.basename(destination));
-  file.set('dependencies', {});
-  file.set('devDependencies', {});
-}
-
-/**
- * Because npm does not allow .gitignore to be published.
- */
-function renameGitigoreFile(destination) {
-  return /** @type {Promise<void>} */(new Promise((res, rej) => 
-    fs.rename(
-      (destination + '/gitignore'),
-      (destination + '/.gitignore'),
-      (err => !!err ? rej(err) : res()),
-    )
-  ));
-}
-
-/**
- * Download the dependencies.
- */
-function downloadNodeModules(destination, useYarn) {
-  const options = { cwd: destination };
-  // Setup dependencies string
-  let depStr = DEPENDENCIES.join(' '),
-    devDepStr = DEV_DEPENDENCIES.join(' ');
-  // Setup download command
-  let downloadLibCmd,
-    downloadDepCmd;
-  if (useYarn) {
-    downloadLibCmd = 'yarn add ' + depStr;
-    downloadDepCmd = 'yarn add ' + devDepStr + ' -D';
-  } else {
-    downloadLibCmd = 'npm i -s ' + depStr;
-    downloadDepCmd = 'npm i -D ' + devDepStr;
-  }
-  // Execute command
-  childProcess.execSync(downloadLibCmd, options);
-  childProcess.execSync(downloadDepCmd, options);
-}
-
-/******************************************************************************
-                                Export
-******************************************************************************/
-
-module.exports = expressGenTs;
+const childProcess = require('child_process');
+const fs = require('fs/promises');
+const path = require('path');
+
+// ========================================================================= //
+//                                 CONSTANTS                                 //
+// ========================================================================= //
+
+const TEMPLATE_DIR = path.join(__dirname, 'template');
+
+// Local build/editor artifacts that only exist when running from a checkout.
+const EXCLUDED_NAMES = new Set([
+  'node_modules',
+  'package-lock.json',
+  'dist',
+  'tsconfig.tsbuildinfo',
+  '.vscode',
+  'database.test.json',
+]);
+
+// ========================================================================= //
+//                                 FUNCTIONS                                 //
+// ========================================================================= //
+
+/**
+ * Entry point: scaffold a new project at `dest` and install its dependencies.
+ * Rejects on any failure so callers can report it and exit non-zero.
+ *
+ * @param {string} dest - Absolute path to create the project in.
+ * @param {object} [options]
+ * @param {boolean} [options.useYarn] - Install with yarn instead of npm.
+ * @param {boolean} [options.force] - Allow writing into a non-empty folder.
+ * @param {boolean} [options.skipInstall] - Don't install dependencies.
+ * @returns {Promise<void>}
+ */
+async function expressGenTs(dest, options = {}) {
+  const { useYarn = false, force = false, skipInstall = false } = options;
+  if (!force) {
+    await assertEmptyOrMissing(dest);
+  }
+  await copyProjectFiles(dest);
+  await setPackageName(dest);
+  await renameGitignoreFile(dest);
+  if (!skipInstall) {
+    installDependencies(dest, useYarn);
+  }
+}
+
+/**
+ * Throw if `dest` exists and has any contents, so existing work is never
+ * overwritten.
+ *
+ * @param {string} dest
+ * @returns {Promise<void>}
+ */
+async function assertEmptyOrMissing(dest) {
+  let entries;
+  try {
+    entries = await fs.readdir(dest);
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  if (entries.length > 0) {
+    throw new Error(
+      `"${dest}" already exists and is not empty. Choose another name or ` +
+        'pass --force to write into it anyway.',
+    );
+  }
+}
+
+/**
+ * Copy the `template` folder into `dest`.
+ *
+ * @param {string} dest
+ * @returns {Promise<void>}
+ */
+function copyProjectFiles(dest) {
+  return fs.cp(TEMPLATE_DIR, dest, {
+    recursive: true,
+    filter: (src) => !EXCLUDED_NAMES.has(path.basename(src)),
+  });
+}
+
+/**
+ * Name the new project after its folder.
+ *
+ * @param {string} dest
+ * @returns {Promise<void>}
+ */
+async function setPackageName(dest) {
+  const pkgPath = path.join(dest, 'package.json');
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+  pkg.name = path.basename(dest);
+  await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+
+/**
+ * Rename the template's `gitignore` to `.gitignore`, because npm does not
+ * allow a `.gitignore` file to be published.
+ *
+ * @param {string} dest
+ * @returns {Promise<void>}
+ */
+function renameGitignoreFile(dest) {
+  return fs.rename(path.join(dest, 'gitignore'), path.join(dest, '.gitignore'));
+}
+
+/**
+ * Install the versions pinned in the template's package.json.
+ *
+ * @param {string} dest
+ * @param {boolean} useYarn
+ * @returns {void}
+ */
+function installDependencies(dest, useYarn) {
+  const cmd = useYarn ? 'yarn install' : 'npm install';
+  childProcess.execSync(cmd, { cwd: dest, stdio: 'inherit' });
+}
+
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
+module.exports = expressGenTs;

package/lib/{project-files → template}/.prettierignore

@@ -3,10 +3,8 @@
 
 # Allow these folders
 !src/
-!test/
-!script/
+!tests/
 
 # Allow all files inside them
 !src/**
-!test/**
-!scripts/**
+!tests/**