create-express-new 0.0.0-stage → 1.0.0

package/lib/wizard.js

@@ -0,0 +1,397 @@
+// Interactive wizard that asks for the same choices as the command line
+// options and returns them in the same shape as the parsed options. Esc (or
+// the left arrow) goes back to the previous question, keeping the answers.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { DEFAULT_PACKAGE_MANAGER, checkDestination, createAppName, planApp } from './app.js'
+import { BACK, CancelError, confirm, erase, hinted, multiselect, rows, select, style, text } from './prompts.js'
+
+// existing files listed before asking about them
+const MAX_LISTED = 5
+
+const VIEWS = [
+  { label: 'pug', value: 'pug', hint: 'default' },
+  { label: 'ejs', value: 'ejs' },
+  { label: 'hbs', value: 'hbs', hint: 'Handlebars' },
+  { label: 'twig', value: 'twig' },
+  { label: 'none', value: false, hint: 'static HTML' }
+]
+
+/**
+ * Walk through the options and return them, or throw CancelError.
+ *
+ * @param {object} io { input, output, cwd }
+ */
+
+export async function wizard (io) {
+  const { output, cwd = process.cwd() } = io
+  const answers = {}
+
+  // the destination checked against the answers, before asking about it
+  let check = null
+
+  output.write('\n' + hinted(style.bold('  create-express-new'), ' create an Express 5 app', output.columns || Infinity) + '\n\n')
+
+  // Each step asks one question, starting from its previous answer, and
+  // keeps the text it prints so going back can erase it.
+  const steps = [
+    {
+      name: 'directory',
+      ask: (step) => askDirectory(io, step, answers.directory, cwd)
+    },
+    {
+      name: 'kind',
+      ask: (step) => step.ask(select, {
+        message: 'What are you building?',
+        initial: answers.kind,
+        choices: [
+          { label: 'Web app', value: 'web', hint: 'server-rendered views' },
+          { label: 'JSON API', value: 'api', hint: 'no views or static files' }
+        ]
+      })
+    },
+    {
+      name: 'view',
+      when: () => answers.kind === 'web',
+      ask: (step) => step.ask(select, { message: 'View engine', initial: answers.view, choices: VIEWS })
+    },
+    {
+      name: 'language',
+      ask: (step) => step.ask(select, {
+        message: 'Language',
+        initial: answers.language,
+        choices: [
+          { label: 'JavaScript', value: 'esm', hint: 'ES modules' },
+          { label: 'TypeScript', value: 'ts', hint: 'runs directly on Node.js 22.18+' },
+          { label: 'JavaScript (CommonJS)', value: 'cjs', hint: 'require() and module.exports' }
+        ]
+      })
+    },
+    {
+      name: 'middleware',
+      ask: (step) => step.ask(multiselect, {
+        message: 'Optional middleware',
+        initial: answers.middleware,
+        choices: [
+          { label: 'helmet', value: 'helmet', hint: 'security headers' },
+          { label: 'compression', value: 'compression', hint: 'gzip/brotli responses' },
+          { label: 'cookie-parser', value: 'cookies', hint: 'req.cookies' },
+          { label: 'cors', value: 'cors', hint: 'cross-origin requests' },
+          { label: 'express-rate-limit', value: 'rate-limit', hint: 'limit requests per client' },
+          // sessions are for web apps
+          ...(answers.kind === 'web' ? [{ label: 'express-session', value: 'session', hint: 'req.session' }] : []),
+          { label: 'multer', value: 'uploads', hint: 'file uploads at /uploads' }
+        ]
+      })
+    },
+    {
+      name: 'csrf',
+      when: () => answers.kind === 'web' && answers.view !== false && answers.middleware.includes('session'),
+      ask: (step) => step.ask(confirm, { message: 'Protect forms with CSRF tokens?', initial: answers.csrf ?? true })
+    },
+    {
+      name: 'logger',
+      ask: (step) => step.ask(select, {
+        message: 'Request logger',
+        initial: answers.logger,
+        choices: [
+          { label: 'morgan', value: 'morgan', hint: 'one readable line per request' },
+          { label: 'pino', value: 'pino', hint: 'JSON logs for log collectors' }
+        ]
+      })
+    },
+    {
+      name: 'extras',
+      ask: (step) => step.ask(multiselect, {
+        message: 'Extras',
+        initial: answers.extras,
+        choices: [
+          { label: 'Dockerfile', value: 'docker', hint: 'production image with a /health check' },
+          { label: 'ESLint', value: 'lint', hint: 'with a lint script' }
+        ]
+      })
+    },
+    {
+      name: 'git',
+      ask: (step) => step.ask(confirm, { message: 'Add a .gitignore?', initial: answers.git ?? true })
+    },
+    {
+      name: 'pm',
+      ask: (step) => step.ask(select, {
+        message: 'Package manager',
+        initial: answers.pm,
+        choices: [
+          { label: 'pnpm', value: 'pnpm', hint: 'recommended, safer installs by default' },
+          { label: 'npm', value: 'npm', hint: 'needs npm 12 or newer' }
+        ]
+      })
+    },
+    {
+      name: 'install',
+      ask: (step) => step.ask(confirm, { message: 'Install dependencies now?', initial: answers.install ?? true })
+    },
+    {
+      name: 'existing',
+      when: () => {
+        check = checkApp(answers, cwd)
+
+        // forget a choice about existing files that are no longer generated
+        if (!check.blockers.length && !check.conflicts.length) delete answers.existing
+        return check.blockers.length > 0 || check.conflicts.length > 0
+      },
+      ask: (step) => askExisting(step, check, answers.existing)
+    },
+    {
+      name: 'create',
+      ask: async (step) => {
+        step.say('\n  Equivalent command:\n  ' + style.cyan(toCommand(toOptions(answers))) + '\n')
+
+        const create = await step.ask(confirm, { message: 'Create the app?', initial: true })
+        if (create === false) throw new CancelError()
+        return create
+      }
+    }
+  ]
+
+  // completed steps, with the text each printed
+  const history = []
+  let index = 0
+
+  while (index < steps.length) {
+    const { name, ask, when } = steps[index]
+
+    if (when && !when()) {
+      index++
+      continue
+    }
+
+    const step = {
+      back: history.length > 0,
+      printed: [],
+      // ask a question, keeping its answer
+      async ask (fn, options) {
+        const value = await fn(io, { ...options, back: this.back })
+        if (value !== BACK) this.printed.push(io.printed)
+        return value
+      },
+      // print text, keeping it
+      say (str) {
+        output.write(str + '\n')
+        this.printed.push(str)
+      }
+    }
+
+    const value = await ask(step)
+
+    if (value === BACK) {
+      // erase what this step printed, and the previous answer, and ask again
+      const previous = history.pop()
+      eraseText(io, [...previous.printed, ...step.printed])
+      index = previous.index
+      continue
+    }
+
+    answers[name] = value
+    history.push({ index, printed: step.printed })
+    index++
+  }
+
+  return toOptions(answers)
+}
+
+/**
+ * Ask for the project directory, confirming a directory that is not empty.
+ */
+
+async function askDirectory (io, step, previous, cwd) {
+  let value = previous ? previous.dir : ''
+
+  for (;;) {
+    const answer = await step.ask(text, {
+      message: 'Project directory',
+      hint: '(. for the current directory)',
+      initial: 'my-app',
+      value,
+      validate: (str) => str.trim() ? null : 'Enter a directory'
+    })
+
+    if (answer === BACK) return BACK
+
+    const dir = answer.trim()
+
+    const resolved = path.resolve(cwd, dir)
+
+    if (isEmpty(resolved)) {
+      return { dir, force: false }
+    }
+
+    const name = resolved === path.resolve(cwd) ? 'The current directory' : 'Directory'
+    const force = await confirm(io, { message: name + ' is not empty. Continue anyway?', initial: false, back: true })
+
+    if (force === true) {
+      step.printed.push(io.printed)
+      return { dir, force: true }
+    }
+
+    // ask for the directory again, in place: empty after declining it, or
+    // starting from it after going back
+    eraseText(io, force === BACK ? step.printed : [...step.printed, io.printed])
+    step.printed = []
+    value = force === BACK ? dir : ''
+  }
+}
+
+/**
+ * Ask what to do with the existing files the app would overwrite, or show
+ * what is in the way of creating it, leaving only going back or cancelling.
+ */
+
+async function askExisting (step, { blockers, conflicts }, previous) {
+  if (blockers.length) {
+    step.say('\n' + blockers.map((blocker) => style.red('  ' + blocker)).join('\n'))
+
+    await step.ask(select, {
+      message: 'Cannot create the app here',
+      choices: [{ label: 'Cancel', value: 'cancel' }]
+    })
+
+    throw new CancelError()
+  }
+
+  const shown = conflicts.slice(0, MAX_LISTED).map((entry) => '    ' + entry.path)
+  if (conflicts.length > MAX_LISTED) shown.push('    and ' + (conflicts.length - MAX_LISTED) + ' more')
+  step.say('\n  These existing files will be overwritten:\n' + style.dim(shown.join('\n')))
+
+  const config = conflicts.filter((entry) => entry.config)
+  const choices = [{ label: 'Overwrite them', value: 'overwrite' }]
+
+  if (config.length === conflicts.length) {
+    choices.push({ label: 'Keep them', value: 'keep' })
+  } else if (config.length) {
+    choices.push({ label: 'Keep my config files', value: 'keep', hint: config.map((entry) => entry.path).join(', ') })
+  }
+
+  choices.push({ label: 'Cancel', value: 'cancel' })
+
+  const answer = await step.ask(select, { message: 'Existing files', initial: previous, choices })
+  if (answer === 'cancel') throw new CancelError()
+  return answer
+}
+
+/**
+ * Check the project directory against the app the answers create.
+ */
+
+function checkApp (answers, cwd) {
+  const options = toOptions(answers)
+  const dir = path.resolve(cwd, options._[0])
+
+  return checkDestination(dir, planApp(createAppName(dir) || 'hello-world', options))
+}
+
+/**
+ * Erase printed text, counting its rows at the current terminal width, as
+ * the terminal may have been resized since it was printed.
+ */
+
+function eraseText (io, printed) {
+  if (printed.length) erase(io, rows(printed.join('\n'), io.output.columns || Infinity))
+}
+
+/**
+ * Options in the shape of the parsed command line options.
+ */
+
+function toOptions (answers) {
+  const { directory, kind, language, middleware = [], extras = [] } = answers
+  const view = kind === 'web' ? answers.view : false
+  const session = kind === 'web' && middleware.includes('session')
+
+  return {
+    _: [directory.dir],
+    '!': [],
+    api: kind === 'api',
+    cjs: language === 'cjs',
+    compression: middleware.includes('compression'),
+    cookies: middleware.includes('cookies'),
+    cors: middleware.includes('cors'),
+    csrf: session && view !== false && answers.csrf === true,
+    docker: extras.includes('docker'),
+    force: directory.force,
+    git: answers.git,
+    helmet: middleware.includes('helmet'),
+    install: answers.install,
+    keepConfig: answers.existing === 'keep',
+    lint: extras.includes('lint'),
+    logger: answers.logger ?? 'morgan',
+    pm: answers.pm ?? DEFAULT_PACKAGE_MANAGER,
+    rateLimit: middleware.includes('rate-limit'),
+    session,
+    ts: language === 'ts',
+    uploads: middleware.includes('uploads'),
+    view
+  }
+}
+
+/**
+ * The command line that generates the same app as the given options.
+ *
+ * @param {object} options
+ */
+
+export function toCommand (options) {
+  const pm = options.pm ?? DEFAULT_PACKAGE_MANAGER
+  const args = [pm, 'create', 'express-new@latest', quote(options._[0])]
+  const flags = []
+
+  if (options.api) flags.push('--api')
+  else if (options.view === false) flags.push('--no-view')
+  else if (options.view !== 'pug') flags.push('--view=' + options.view)
+
+  if (options.ts) flags.push('--ts')
+  if (options.cjs) flags.push('--cjs')
+  if (options.helmet) flags.push('--helmet')
+  if (options.compression) flags.push('--compression')
+  if (options.cookies) flags.push('--cookies')
+  if (options.cors) flags.push('--cors')
+  if (options.rateLimit) flags.push('--rate-limit')
+  if (options.session) flags.push('--session')
+  if (options.csrf) flags.push('--csrf')
+  if (options.uploads) flags.push('--uploads')
+  if (options.logger && options.logger !== 'morgan') flags.push('--logger=' + options.logger)
+  if (options.docker) flags.push('--docker')
+  if (options.lint) flags.push('--lint')
+  if (pm !== DEFAULT_PACKAGE_MANAGER) flags.push('--pm=' + pm)
+  if (!options.git) flags.push('--no-git')
+  if (options.force) flags.push('--force')
+  if (options.keepConfig) flags.push('--keep-config')
+
+  // npm create keeps the options before `--` for itself
+  if (flags.length && pm === 'npm') args.push('--')
+  args.push(...flags)
+
+  return args.join(' ')
+}
+
+/**
+ * Check if a directory is missing or empty.
+ */
+
+function isEmpty (dir) {
+  try {
+    return fs.readdirSync(dir).length === 0
+  } catch (err) {
+    if (err.code === 'ENOENT') return true
+    if (err.code === 'ENOTDIR') return false
+    throw err
+  }
+}
+
+/**
+ * Quote a shell argument when needed.
+ */
+
+function quote (arg) {
+  return /^[\w./@:-]+$/.test(arg) ? arg : JSON.stringify(arg)
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "create-express-new",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Express 5 application generator: ESM, TypeScript and CommonJS app templates. A modern successor to express-generator.",
+  "version": "1.0.0",
+  "author": "Michael Caines (https://github.com/w0244079)",
+  "contributors": [
+    "TJ Holowaychuk <tj@vision-media.ca>",
+    "Aaron Heckmann <aaron.heckmann+github@gmail.com>",
+    "Ciaran Jessup <ciaranj@gmail.com>",
+    "Douglas Christopher Wilson <doug@somethingdoug.com>",
+    "Guillermo Rauch <rauchg@gmail.com>",
+    "Jonathan Ong <me@jongleberry.com>",
+    "Roman Shtylman <shtylman+expressjs@gmail.com>"
+  ],
+  "keywords": [
+    "express",
+    "express-generator",
+    "express5",
+    "generator",
+    "template",
+    "starter",
+    "scaffold",
+    "boilerplate",
+    "cli",
+    "esm",
+    "typescript",
+    "web",
+    "api"
+  ],
+  "repository": "github:w0244079/create-express-new",
+  "homepage": "https://github.com/w0244079/create-express-new#readme",
+  "bugs": "https://github.com/w0244079/create-express-new/issues",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-express-new": "./bin/express-cli.js",
+    "express": "./bin/express-cli.js"
+  },
+  "dependencies": {
+    "ejs": "^6.0.1"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.5",
+    "mocha": "^12.0.3",
+    "neostandard": "^0.13.0",
+    "supertest": "^7.3.0",
+    "tree-kill": "^1.2.2",
+    "validate-npm-package-name": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=22.9"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "LICENSE",
+    "bin/",
+    "lib/",
+    "templates/"
+  ],
+  "scripts": {
+    "lint": "eslint .",
+    "test": "mocha --reporter spec --bail --check-leaks test/",
+    "test-ci": "mocha --reporter spec --check-leaks test/",
+    "versions": "node scripts/versions.js",
+    "prepublishOnly": "npm run lint && npm run test-ci"
+  }
+}

package/templates/app/Dockerfile.ejs

@@ -0,0 +1,64 @@
+# syntax=docker/dockerfile:1
+
+<% if (pm === 'pnpm') { -%>
+# Production image. Build it after `pnpm install`, which creates the
+# pnpm-lock.yaml that the image installs from:
+<% } else { -%>
+# Production image. Build it after `npm install`, which creates the
+# package-lock.json that `npm ci` needs:
+<% } -%>
+#
+#   docker build -t <%- name %> .
+#   docker run -p 3000:3000 <%- name %>
+
+# Dependencies are installed in their own stage, which keeps the package
+# manager out of the final image.
+
+# the latest Node.js 22 release, matching the minimum version in package.json
+FROM node:22-slim AS dependencies
+
+WORKDIR /app
+
+<% if (pm === 'pnpm') { -%>
+# the package manager this app requires in package.json; it switches to the
+# pnpm version recorded in pnpm-lock.yaml
+<% } else { -%>
+# the package manager this app requires in package.json
+<% } -%>
+RUN npm install -g <%- pm %>@<%- pmVersion %>
+
+# install production dependencies first, so they are cached between builds
+<% if (pm === 'pnpm') { -%>
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+RUN pnpm install --frozen-lockfile --prod
+<% } else { -%>
+COPY package*.json .npmrc ./
+RUN npm ci --omit=dev
+<% } -%>
+
+FROM node:22-slim
+
+ENV NODE_ENV=production
+WORKDIR /app
+
+# the dependencies installed above
+COPY --from=dependencies /app/node_modules ./node_modules
+
+# copy the app owned by the unprivileged node user, which runs it, so it can
+# read the files whatever their permissions on the build machine
+COPY --chown=node:node . .
+<% if (uploads) { -%>
+
+# a folder for uploaded files that the node user can write to; files saved
+# in a container are lost when it is replaced, so mount a volume here
+RUN mkdir -p uploads && chown node:node uploads
+<% } -%>
+USER node
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=3s \
+  CMD node -e "fetch('http://localhost:' + (process.env.PORT || 3000) + '/health').then((res) => process.exit(res.ok ? 0 : 1), () => process.exit(1))"
+
+# run node directly, so it receives SIGTERM and shuts down gracefully
+CMD ["node", "<%- www %>"]

package/templates/app/app.js.ejs

@@ -0,0 +1,163 @@
+<% if (esm) { -%>
+<% if (httpErrors) { -%>
+import createError from 'http-errors';
+<% } -%>
+import express from 'express';
+<% if (ts) { -%>
+import type { NextFunction, Request, Response } from 'express';
+<% if (httpErrors) { -%>
+import type { HttpError } from 'http-errors';
+<% } -%>
+<% } -%>
+<% if (!api) { -%>
+import path from 'node:path';
+<% } -%>
+<% Object.keys(modules).sort().forEach(function (variable) { -%>
+import <%- named.has(variable) ? '{ ' + variable + ' }' : variable %> from '<%- modules[variable] %>';
+<% }); -%>
+
+<% Object.keys(localModules).sort().forEach(function (variable) { -%>
+import <%- variable %> from '<%- localModules[variable] %>';
+<% }); -%>
+<% } else { -%>
+<% if (httpErrors) { -%>
+const createError = require('http-errors');
+<% } -%>
+const express = require('express');
+<% if (!api) { -%>
+const path = require('node:path');
+<% } -%>
+<% Object.keys(modules).sort().forEach(function (variable) { -%>
+const <%- named.has(variable) ? '{ ' + variable + ' }' : variable %> = require('<%- modules[variable] %>');
+<% }); -%>
+
+<% Object.keys(localModules).sort().forEach(function (variable) { -%>
+const <%- variable %> = require('<%- localModules[variable] %>');
+<% }); -%>
+<% } -%>
+
+const app = express();
+
+<% if (trustProxy) { -%>
+// behind a load balancer or other proxy, trust the X-Forwarded-* headers it
+// sets, so req.ip and req.secure describe the client: TRUST_PROXY is the
+// number of proxies, or their addresses
+if (process.env.TRUST_PROXY) {
+  const hops = Number(process.env.TRUST_PROXY);
+  app.set('trust proxy', Number.isInteger(hops) ? hops : process.env.TRUST_PROXY);
+}
+
+<% } -%>
+<% if (session) { -%>
+// session cookies are signed with SESSION_SECRET, which production requires
+if (!process.env.SESSION_SECRET && app.get('env') === 'production') {
+  throw new Error('Set SESSION_SECRET to use sessions in production');
+}
+
+<% } -%>
+// health check for load balancers and containers, defined before the
+// middleware so it stays fast and out of the request logs
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok' });
+});
+
+<% if (view) { -%>
+// view engine setup
+<% if (view.render) { -%>
+app.engine('<%- view.engine %>', <%- view.render %>);
+<% } -%>
+app.set('views', path.join(<%- dirname %>, 'views'));
+app.set('view engine', '<%- view.engine %>');
+
+<% } -%>
+<% uses.forEach(function (use) { -%>
+app.use(<%- use %>);
+<% }); -%>
+
+<% mounts.forEach(function (mount) { -%>
+app.use(<%= mount.path %>, <%- mount.code %>);
+<% }); -%>
+
+<% if (view) { -%>
+// catch 404 and forward to error handler
+app.use((req, res, next) => {
+  next(createError(404));
+});
+
+// error handler
+<% if (ts) { -%>
+app.use((err: HttpError, req: Request, res: Response, next: NextFunction) => {
+<% } else { -%>
+app.use((err, req, res, next) => {
+<% } -%>
+  const status = err.status || 500;
+
+  // log server errors, which are bugs, but not client errors
+  if (status >= 500) console.error(err);
+
+  const development = req.app.get('env') === 'development';
+
+  // set locals, only exposing client error messages, or every error in
+  // development, and only providing the error in development
+  res.locals.message = err.expose || development ? err.message : 'Internal Server Error';
+  res.locals.title = res.locals.message;
+  res.locals.status = status;
+  res.locals.error = development ? err : {};
+
+  // render the error page
+  res.status(status);
+  res.render('error');
+});
+
+<% } else if (api) { -%>
+// catch 404 and forward to error handler
+app.use((req, res, next) => {
+  next(createError(404));
+});
+
+// error handler
+<% if (ts) { -%>
+app.use((err: HttpError, req: Request, res: Response, next: NextFunction) => {
+<% } else { -%>
+app.use((err, req, res, next) => {
+<% } -%>
+  const status = err.status || 500;
+  const development = req.app.get('env') === 'development';
+
+  // log server errors, which are bugs, but not client errors
+  if (status >= 500) console.error(err);
+
+  // only expose client error messages, or every error in development
+  res.status(status).json({
+    error: err.expose || development ? err.message : 'Internal Server Error',
+    ...(development && { stack: err.stack })
+  });
+});
+
+<% } else { -%>
+// error handler, responding with plain text
+<% if (ts) { -%>
+app.use((err: Error & { status?: number; expose?: boolean }, req: Request, res: Response, next: NextFunction) => {
+<% } else { -%>
+app.use((err, req, res, next) => {
+<% } -%>
+  const status = err.status || 500;
+  const development = req.app.get('env') === 'development';
+
+  // log server errors, which are bugs, but not client errors
+  if (status >= 500) console.error(err);
+
+  // only expose client error messages, or every error and its stack in development
+  let message = 'Internal Server Error';
+  if (development) message = err.stack ?? err.message;
+  else if (err.expose) message = err.message;
+
+  res.status(status).type('text').send(message);
+});
+
+<% } -%>
+<% if (esm) { -%>
+export default app;
+<% } else { -%>
+module.exports = app;
+<% } -%>