create-express-new 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-10
+
+The first release of `create-express-new`, a fork of
+[`express-generator`](https://github.com/expressjs/generator) 4.16.1 reimagined for Express 5 and
+current Node.js. See [Changes from express-generator](docs/changes-from-express-generator.md) for
+the full list and a table for migrating commands.
+
+### Added
+
+- `npm create express-new@latest`, with an interactive wizard when run without arguments in a
+  terminal; Esc goes back, and it shows the equivalent command and offers to install the dependencies
+- ES module output by default, `--cjs` for CommonJS and `--ts` for TypeScript, run directly by
+  Node.js with no build step
+- `--api` for JSON APIs, with JSON 404 and error responses that hide server error details in
+  production
+- `--helmet`, `--compression`, `--cookies` and `--cors` for opt-in middleware
+- `--docker` for a production Dockerfile running as the `node` user, with a `HEALTHCHECK`
+- `--lint` for ESLint, including typescript-eslint for TypeScript apps
+- A `GET /health` endpoint, `.env` loading with a generated `.env.example`, an `npm run dev` script
+  using `node --watch`, and a `node:test` test suite in every app
+- Graceful shutdown on SIGINT and SIGTERM, and a modern `.gitignore` (skip it with `--no-git`)
+- `--rate-limit` adds express-rate-limit, limiting each client to 100 requests every 15 minutes
+  (`RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`), after static files and never on `/health`
+- `--session` adds express-session for web apps, with `SameSite=Lax` cookies that are `Secure` over
+  HTTPS, and refuses to start in production without `SESSION_SECRET`
+- `--csrf` adds csrf-sync CSRF protection to apps with `--session` and a view engine, with the token
+  in views as `csrfToken` and in a `csrf-token` meta tag in the page layout
+- `--uploads` adds multer and a `POST /uploads` route for web apps and JSON APIs, saving one file of
+  up to 5 MB (`UPLOAD_MAX_SIZE`) of an allowed type in an ignored `uploads/` folder, with an upload
+  form in apps with views; with `--csrf` it checks the token before saving the file, and with
+  `--docker` the image has a writable `uploads` folder
+- With `--csrf`, an example form at `/users/new` and CSRF setup in its own `csrf.js`
+- `--logger=pino` logs requests as JSON with pino-http instead of morgan, pretty printed by the
+  `dev` script
+- `TRUST_PROXY` sets the proxies the app trusts, for apps with `--rate-limit` or `--session`
+- The wizard offers express-rate-limit and express-session (for web apps) with the other middleware,
+  asks about CSRF protection when sessions are chosen, and asks which request logger to use
+- `--keep-config` keeps existing config files (`.env.example`, `Dockerfile`, `.dockerignore`,
+  `tsconfig.json`, `eslint.config.*`) when generating into a non-empty directory
+- The wizard lists the existing files an app would overwrite and asks whether to overwrite them,
+  keep the config files or cancel
+- The wizard's directory prompt hints that `.` is the current directory
+- `--pm` sets the package manager an app requires, `pnpm` (the default) or `npm`, as
+  `devEngines.packageManager` in `package.json`, so other package managers refuse to install the
+  app or run its scripts
+- Settings that protect installs from compromised packages in every app: `pnpm-workspace.yaml` for
+  pnpm apps (new releases wait 3 days, install scripts of dependencies are not run, dependencies of
+  dependencies cannot come from git or URLs, releases with weaker proof of origin than earlier ones
+  are refused, and the pnpm version recorded in `pnpm-lock.yaml` is the one that runs) and `.npmrc`
+  for npm apps (new releases wait 3 days; npm 12 does not run install scripts or allow git
+  dependencies by default); `--keep-config` keeps existing ones
+- The wizard asks which package manager the app requires and installs dependencies with it
+- `npm run versions` reports a version floor released under 3 days ago as too new for generated apps
+  to install, and `--update` lowers it; floors are only raised to releases at least 7 days old
+
+### Changed
+
+- Generates Express 5 apps with current versions of every dependency; apps require Node.js 22.9 or
+  newer (22.18 for TypeScript)
+- The default view engine is pug (was jade); `--view=jade` warns and generates pug
+- `bin/www` is now `bin/www.js`, a short script built on `app.listen()`
+- cookie-parser is no longer included by default; use `--cookies`
+- The generator is an ES module with a single dependency (ejs)
+- Apps require pnpm 11 or newer by default, and `npm install` is refused in them; pass
+  `--pm=npm` for an app that requires npm, which now has to be npm 12 or newer
+- The usage, next steps, `.env.example` and the wizard's equivalent command name the app's package
+  manager, such as `pnpm create express-new@latest my-app --ts` and `pnpm dev`
+- `--docker` images install dependencies with the app's package manager, at a fixed version, in a
+  build stage of their own, so the package manager is not in the final image
+- Every app's error handler logs server errors (5xx) with `console.error`, which no error handler
+  did before, so a 500 only showed as a status in the request log
+- An existing `.gitignore` gets the missing lines added instead of being replaced
+- Existing files with the same contents are left alone, logged as `identical`
+- The command line lists the files it would overwrite before asking to continue in a non-empty
+  directory
+- A warning lists existing files the new app does not use but other options generate (code in the
+  other language, the other ESLint config, other view engines' templates, pnpm settings in an npm
+  app); they are not removed
+
+### Fixed
+
+- Error pages show the status code in every environment, not only in development, and have a title
+- `error.ejs` is a full HTML page with the stylesheet, like the other engines' error pages
+- twig layouts escape the page title, which error pages set to the error message
+- Web apps with views no longer show server errors' messages outside development, only
+  `Internal Server Error`, as JSON APIs already did
+- `--no-view` apps have their own error handler, responding with plain text and logging only server
+  errors, instead of Express's default handler logging the stack of every error, including client
+  errors such as invalid JSON
+- twig error pages escape the error message and stack, as twig.js does not escape output by default
+- An overwritten or identical `bin/www` is made executable, as writing an existing file kept its mode
+- A file where the app needs a folder (or a folder where it needs a file) is reported before
+  anything is written, instead of failing with a partly generated app
+- The wizard reports a package manager that is not installed once, with where to get it, instead of
+  printing the failure and next steps twice
+
+### Removed
+
+- The dust, hjs (Hogan.js), jade and vash view engines
+- CSS preprocessor support (`--css`); apps use plain CSS
+- The `-e/--ejs`, `--hbs`, `--pug` and `-H/--hogan` aliases; use `--view=<engine>`
+- The `debug` package and `DEBUG=...` start instructions
+
+[Unreleased]: https://github.com/w0244079/create-express-new/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/w0244079/create-express-new/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+(The MIT License)
+
+Copyright (c) 2009-2013 TJ Holowaychuk <tj@vision-media.ca>
+Copyright (c) 2015-2018 Douglas Christopher Wilson <doug@somethingdoug.com>
+Copyright (c) 2026 Michael Caines
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,282 @@
-# Temporary Holding Version
+# create-express-new
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An application generator for [Express 5](https://expressjs.com/), creating web apps or JSON APIs
+as ES modules, TypeScript or CommonJS that run on current Node.js with no build step.
+
+[![NPM Version][npm-image]][npm-url]
+[![NPM Downloads][downloads-image]][npm-url]
+[![Node.js Version][node-image]][npm-url]
+[![License][license-image]](LICENSE)
+[![CI][github-actions-ci-image]][github-actions-ci-url]
+[![OpenSSF Scorecard][scorecard-image]][scorecard-url]
+
+`create-express-new` is a fork of [`express-generator`](https://github.com/expressjs/generator),
+the original Express application generator, reimagined for today's Express apps. It keeps the
+familiar `express` command and project layout, and updates everything it generates for Express 5
+and modern Node.js. It is not affiliated with or endorsed by the Express project.
+
+## Quick Start
+
+Run the generator with no arguments to be guided through the options (requires Node.js 22.9 or newer):
+
+```bash
+$ pnpm create express-new@latest
+```
+
+`npm create express-new@latest` starts the same wizard. It asks for:
+
+- the project directory (`.` for the current directory)
+- a web app or a JSON API, and the view engine
+- the language: JavaScript, TypeScript or CommonJS
+- optional middleware, and CSRF protection with sessions
+- the request logger
+- extras: a Dockerfile and ESLint
+- a `.gitignore`
+- the [package manager](#package-manager) the app requires: pnpm, or npm
+
+Esc (or ←) goes back a question, keeping your answers. At the end the wizard shows the equivalent
+command, to repeat the setup or use in scripts, and offers to install the dependencies.
+
+In a directory that already has files:
+
+- Files the app would replace are listed, and the wizard asks whether to overwrite them, keep your
+  config files (see `--keep-config` below) or cancel.
+- Files with the same contents are left alone.
+- An existing `.gitignore` is never replaced; the lines it is missing are added at the end.
+- A file where the app needs a folder, or a folder where it needs a file, stops anything being written.
+- Files from an earlier app with other options, such as an `app.js` next to a new `app.ts`, are left
+  in place and listed in a warning.
+
+Or pass the directory and options directly:
+
+```bash
+$ pnpm create express-new@latest my-app --ts --helmet
+$ cd my-app
+$ pnpm install
+```
+
+With `npm create`, put the options after `--`: `npm create express-new@latest my-app -- --ts --helmet`.
+`npx create-express-new my-app --ts --helmet` needs no `--`. Either way the app requires pnpm unless
+you add `--pm=npm`.
+
+Start it at `http://localhost:3000/`, and run its tests, written with the built-in
+[`node:test`](https://nodejs.org/api/test.html) runner:
+
+```bash
+$ pnpm dev      # restarts on change
+$ pnpm start    # without restarting
+$ pnpm test
+```
+
+An app generated with `--pm=npm` uses `npm install`, `npm run dev`, `npm start` and `npm test`.
+
+You can also install the generator globally, which provides the `express` command:
+
+```bash
+$ npm install -g create-express-new
+$ express --view=ejs --helmet my-app
+```
+
+The original `express-generator` provides an `express` command too, so install only one of them globally.
+
+## What You Get
+
+```
+my-app
+├── .env.example      # example environment variables; copy to .env
+├── .gitignore        # ignores node_modules, .env files, logs and coverage
+├── app.js            # the Express app: middleware, views, routes, error handling
+├── bin/www.js        # starts the server, with graceful shutdown on SIGINT/SIGTERM
+├── package.json      # "type": "module", start/dev/test scripts
+├── public/           # static files, including stylesheets/style.css
+├── routes/           # index.js and users.js routers
+├── test/app.test.js  # node:test tests for the app
+└── views/            # error, index and layout templates (pug by default)
+```
+
+Every app has a `GET /health` endpoint that responds with `{ "status": "ok" }`, for load balancers,
+container health checks and uptime monitors. It is defined before the middleware, so it stays fast and
+out of the request logs.
+
+Server errors (5xx) are logged with `console.error`; client errors (4xx), such as a 404, are not.
+Errors render with the `error` view, or as plain text with `--no-view`. Client errors show their
+message. Server errors only say `Internal Server Error` outside development, so internal details are
+never sent; development shows every error's message and stack.
+
+### JSON APIs
+
+`--api` generates a JSON API instead of a web app: no views, static files or form parsing, and
+routes that respond with JSON.
+
+```
+my-api
+├── app.js            # JSON body parsing, routes, JSON 404 and error handling
+├── bin/www.js
+├── package.json
+├── routes/           # index.js and users.js, responding with JSON
+└── test/app.test.js
+```
+
+Errors are always JSON, such as `{ "error": "Not Found" }`, and follow the same rules as web apps:
+client errors include their message, server errors only say `Internal Server Error` in production,
+and development adds the stack trace. Express runs in development mode unless `NODE_ENV` is set, so
+set `NODE_ENV=production` when you deploy.
+
+`--api` works with `--cjs`, `--ts` and the optional middleware, but not with `--view`.
+
+### Module formats
+
+- **ES modules** (default): `import`/`export`, `import.meta.dirname` and `node:` built-ins.
+- **CommonJS** (`--cjs`): the same app with `require()`/`module.exports`.
+- **TypeScript** (`--ts`): `.ts` files that Node.js 22.18+ runs directly by
+  [stripping types](https://nodejs.org/api/typescript.html#type-stripping), so there is no build step.
+  Includes a strict `tsconfig.json`, the `@types` packages the app needs and a `typecheck`
+  script that runs `tsc`. `--ts` cannot be combined with `--cjs`.
+
+### Configuration
+
+The `start` and `dev` scripts load environment variables from a `.env` file when one exists, using
+Node.js's built-in [`--env-file-if-exists`](https://nodejs.org/api/cli.html#--env-file-if-existsfile),
+so no `dotenv` package is needed. Start from the generated example:
+
+```bash
+$ cp .env.example .env
+```
+
+Variables already set in the environment take precedence over `.env`, so your hosting platform's
+settings always win. The `dev` script restarts when `.env` changes. The generated `.gitignore` keeps
+`.env`, and every other `.env.*` file except `.env.example`, out of version control.
+
+### Optional middleware
+
+By default, generated apps include only request logging, body parsing and static files (no static
+files with `--api`). Add more with:
+
+- `--helmet`: [helmet](https://helmetjs.github.io/) security headers
+- `--compression`: gzip/brotli response [compression](https://github.com/expressjs/compression)
+- `--cookies`: [cookie-parser](https://github.com/expressjs/cookie-parser), for reading `req.cookies`
+- `--cors`: [cors](https://github.com/expressjs/cors), allowing requests from other origins
+- `--rate-limit`: [express-rate-limit](https://express-rate-limit.mintlify.app/), limiting each client
+  to 100 requests every 15 minutes
+- `--session` (web apps only): [express-session](https://github.com/expressjs/session), for `req.session`
+- `--csrf` (with `--session` and a view engine): [csrf-sync](https://github.com/Psifi-Solutions/csrf-sync)
+  CSRF protection for forms
+- `--uploads`: [multer](https://github.com/expressjs/multer) and a `POST /uploads` route that takes one
+  file of up to 5 MB
+
+[Optional middleware](docs/middleware.md) covers each one's settings and environment variables,
+sending the CSRF token from forms and JavaScript, running behind a proxy, and how
+[uploaded files](docs/middleware.md#file-uploads) are stored and checked.
+
+### Request logging
+
+Requests are logged with [morgan](https://github.com/expressjs/morgan) by default, one readable line
+per request. `--logger=pino` uses [pino-http](https://github.com/pinojs/pino-http) instead, which logs
+JSON for log collectors and adds `req.log` for your own logs. The `dev` script pipes them through
+[pino-pretty](https://github.com/pinojs/pino-pretty) to keep them readable. Either way, requests are
+not logged while the tests run.
+
+### Package manager
+
+Every app requires one package manager, pnpm by default or npm with `--pm=npm`, so other package
+managers refuse to install the app or run its scripts. It also has settings that protect installs
+from compromised packages: new releases wait 3 days before they are installed, and the install
+scripts of dependencies are not run. An npm app needs npm 12 or newer, which does not come with
+Node.js 22 or 24.
+
+[Package manager](docs/package-manager.md) compares the pnpm and npm settings, and covers allowing
+a dependency's install script, installing a release sooner and changing package manager later.
+
+### Docker
+
+`--docker` adds a `Dockerfile` and `.dockerignore` for a production image. Install dependencies
+first, as the image installs from the lockfile:
+
+```bash
+$ pnpm install
+$ docker build -t my-app .
+$ docker run -p 3000:3000 my-app
+```
+
+The image:
+
+- is based on `node:22-slim`, the latest release of the minimum supported Node.js version
+- installs only production dependencies, in a build stage of their own, so the package manager is
+  not in the final image
+- runs the app as the unprivileged `node` user with `NODE_ENV=production`
+- checks `/health` with a `HEALTHCHECK`
+- runs `node` directly, so it receives `SIGTERM` and shuts down gracefully
+- does not copy `.env` files; set environment variables with your container platform instead. With
+  `--session`, the app needs `SESSION_SECRET` to start, such as
+  `docker run -e SESSION_SECRET=... -p 3000:3000 my-app`
+
+### Linting
+
+`--lint` adds [ESLint](https://eslint.org/) with its recommended rules and a `lint` script. With
+`--ts` it also adds [typescript-eslint](https://typescript-eslint.io/); as typescript-eslint does not
+support TypeScript 7 yet, these apps use TypeScript 6.
+
+## Command Line Options
+
+    -v, --view <engine>  add view <engine> support (ejs|hbs|pug|twig) (defaults to pug)
+        --no-view        use static html instead of view engine
+        --api            generate a JSON API, without views or static files
+        --cjs            generate CommonJS modules instead of ES modules
+        --ts             generate TypeScript, run directly by Node.js
+        --helmet         add helmet middleware for security headers
+        --compression    add compression middleware for gzip/brotli responses
+        --cookies        add cookie-parser middleware
+        --cors           add cors middleware for cross-origin requests
+        --rate-limit     add express-rate-limit to limit requests per client
+        --session        add express-session for sessions (not with --api)
+        --csrf           add CSRF protection for forms (needs --session)
+        --uploads        add multer and an upload route at /uploads
+        --logger <name>  request logger (morgan|pino) (defaults to morgan)
+        --docker         add a Dockerfile for a production image
+        --lint           add ESLint and a lint script
+        --pm <name>      package manager the app requires (pnpm|npm) (defaults to pnpm)
+        --no-git         skip the .gitignore
+    -f, --force          force on non-empty directory
+        --keep-config    keep existing config files (.env.example, Dockerfile,
+                         .dockerignore, tsconfig.json, eslint.config.*,
+                         pnpm-workspace.yaml, .npmrc)
+        --version        output the version number
+    -h, --help           output usage information
+
+## Changes From express-generator
+
+This fork started from `express-generator` 4.16.1. It generates Express 5 apps as ES modules, with
+pug in place of jade, for Node.js 22.9 or newer. `--view=<engine>` replaces the `--ejs`, `--hbs` and
+`--pug` aliases, and apps use plain CSS instead of a CSS preprocessor.
+
+- [Changes from express-generator](docs/changes-from-express-generator.md): everything added,
+  changed and removed, and a table for migrating commands
+- [Using Sass](docs/sass.md): adding Sass to a generated app
+
+## Contributing
+
+```bash
+$ npm install
+$ npm test       # generates, installs and runs apps for each option
+$ npm run lint
+```
+
+The tests install the generated apps with pnpm, so [install pnpm](https://pnpm.io/installation)
+first. The tests that install an npm app are skipped unless your npm is version 12 or newer.
+
+See [Maintaining](docs/maintaining.md) for keeping the dependency versions of generated apps current,
+and for releasing.
+
+## License
+
+[MIT](LICENSE). Originally created by TJ Holowaychuk and the Express contributors.
+
+[npm-image]: https://img.shields.io/npm/v/create-express-new.svg
+[npm-url]: https://www.npmjs.com/package/create-express-new
+[downloads-image]: https://img.shields.io/npm/dm/create-express-new.svg
+[node-image]: https://img.shields.io/node/v/create-express-new.svg
+[license-image]: https://img.shields.io/npm/l/create-express-new.svg
+[github-actions-ci-image]: https://github.com/w0244079/create-express-new/actions/workflows/ci.yml/badge.svg
+[github-actions-ci-url]: https://github.com/w0244079/create-express-new/actions/workflows/ci.yml
+[scorecard-image]: https://api.scorecard.dev/projects/github.com/w0244079/create-express-new/badge
+[scorecard-url]: https://scorecard.dev/viewer/?uri=github.com/w0244079/create-express-new