express-generator-typescript 2.8.0 → 2.9.0

package/README.md

@@ -1,16 +1,15 @@
 <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>
+  <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

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,153 +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',
-  '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',
-  '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/**

package/lib/template/README.md

@@ -0,0 +1,50 @@
+## About
+
+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>
+
+
+## Available Scripts
+
+### `npm run install:clean`
+
+Remove the existing `node_modules/` folder, `package-lock.json`, and reinstall all library modules.
+
+### `npm run dev` 
+
+Run the server in development with hot reloading and browser refresh (see `package.json` for all `npm run dev` variations)<br/>
+
+**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.
+
+### `npm test`
+
+Run unit-tests with <a href="https://vitest.dev/guide/">vitest</a>.
+
+### `npm run lint`
+
+Check for linting errors.
+
+### `npm run format`
+
+Format `src/` and `tests/` with prettier.
+
+### `npm run build`
+
+Build the project for production.
+
+### `npm start`
+
+Run the production build (Must be built first).
+
+### `npm run typecheck`
+
+Check for typescript errors.
+
+<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.

package/lib/template/bs-config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  proxy: "http://localhost:3000/", // The address where your Express app runs
+  open: true, // Avoid reopening the browser on every nodemon restart
+  port: 3001, // The port BrowserSync will run on
+  files: ["src/**/*.*"], // Files to watch
+  ignore: ['**/node_modules/**', '**/repos/**/*.json'],
+  reloadDelay: 500, // Wait for nodemon to restart
+};

package/lib/{project-files → template}/config/.env.development

@@ -1,15 +1,13 @@
-## Environment ##
+# ---- Environment
 NODE_ENV=development
 
 
-## Server ##
+# ---- Server
 PORT=3000
-HOST=localhost
 
 
-## Setup jet-logger ##
+# ---- Setup jet-logger
 JET_LOGGER_MODE=console
 JET_LOGGER_FILEPATH=jet-logger.log
-JET_LOGGER_TIMESTAMP=true
+JET_LOGGER_SHOW_TIME=true
 JET_LOGGER_FORMAT=line
-

package/lib/{project-files → template}/config/.env.production

@@ -1,14 +1,13 @@
-## Environment ##
+# ---- Environment
 NODE_ENV=production
 
 
-## Server ##
+# ---- Server
 PORT=8081
-HOST=localhost
 
 
-## Setup jet-logger ##
+# ---- Setup jet-logger
 JET_LOGGER_MODE=file
 JET_LOGGER_FILEPATH=jet-logger.log
-JET_LOGGER_TIMESTAMP=true
+JET_LOGGER_SHOW_TIME=true
 JET_LOGGER_FORMAT=line

package/lib/{project-files → template}/config/.env.test

@@ -1,14 +1,13 @@
-## Environment ##
+# ---- Environment
 NODE_ENV=test
 
 
-## Server ##
+# ---- Server
 PORT=4000
-HOST=localhost
 
 
-## Setup jet-logger ##
+# ---- Setup `jet-logger`
 JET_LOGGER_MODE=console
 JET_LOGGER_FILEPATH=jet-logger.log
-JET_LOGGER_TIMESTAMP=true
+JET_LOGGER_SHOW_TIME=true
 JET_LOGGER_FORMAT=line

package/lib/{project-files → template}/eslint.config.ts

@@ -4,6 +4,10 @@ import n from 'eslint-plugin-n';
 import { defineConfig, globalIgnores } from 'eslint/config';
 import tseslint from 'typescript-eslint';
 
+// ========================================================================= //
+//                                  EXPORT                                   //
+// ========================================================================= //
+
 export default defineConfig([
   // global ignores
   globalIgnores(['**/dist/**', '**/public/**/lib/**']),

package/lib/template/gitignore

@@ -0,0 +1,10 @@
+**/node_modules
+dist/
+**/**/*.log
+tsconfig.tsbuildinfo
+
+# Rewritten on every test run
+src/repos/common/database.test.json
+
+# Keep production secrets out of git; share values through your deploy tooling
+config/.env.production

package/lib/template/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "express-typescript-example",
+  "version": "0.1.0",
+  "scripts": {
+    "build": "shx rm -rf dist && npm run lint && tsc --project 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\"",
+    "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",
+    "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",
+    "express": "^5.2.1",
+    "helmet": "^8.3.0",
+    "jet-env": "^1.1.6",
+    "jet-id": "^1.3.1",
+    "jet-logger": "3.0.0",
+    "jet-paths": "^4.0.1",
+    "jet-validators": "^2.3.1",
+    "jsonfile": "^6.2.1",
+    "module-alias": "^2.3.4",
+    "morgan": "^1.12.1",
+    "tspo": "^1.0.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@swc/core": "^1.16.2",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/express": "^5.0.6",
+    "@types/jsonfile": "^6.1.4",
+    "@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",
+    "eslint": "^10.11.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-n": "^18.3.0",
+    "jiti": "^2.7.0",
+    "nodemon": "^3.1.14",
+    "prettier": "^3.9.9",
+    "shx": "^0.4.0",
+    "supertest": "^7.3.0",
+    "ts-node": "^10.9.2",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.70.1",
+    "vitest": "^5.0.2"
+  },
+  "allowScripts": {
+    "@swc/core@1.16.2": true
+  }
+}