create-express-new 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,21 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-10-11
+
+### Added
+
+- `--api` with a view engine, such as `--api --view=pug`, generates a web app with a JSON API: a
+  `routes/api.js` router at `/api`, and JSON responses for every error under `/api`. The wizard offers
+  it as "Web app with a JSON API"
+- `--cors-scope` and `--csrf-scope`, for a web app with a JSON API, choose whether other origins can
+  call only the API (default) or the whole app, and whether the API needs the CSRF token (default) or
+  only the pages do; the wizard asks both
+
+### Changed
+
+- `--api` with `--view` is no longer an error, and `--session` and `--csrf` can be used with them
+
 ## [1.1.0] - 2026-10-10
 
 ### Added
@@ -121,6 +136,7 @@ the full list and a table for migrating commands.
 - 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.1.0...HEAD
+[Unreleased]: https://github.com/w0244079/create-express-new/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/w0244079/create-express-new/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/w0244079/create-express-new/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/w0244079/create-express-new/releases/tag/v1.0.0

package/README.md

@@ -26,7 +26,7 @@ $ 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
+- a web app, a JSON API or a web app with a JSON API, and the view engine
 - the language: JavaScript, TypeScript or CommonJS
 - optional middleware, and CSRF protection with sessions
 - the request logger
@@ -122,7 +122,40 @@ client errors include their message, server errors only say `Internal Server Err
 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`.
+`--api` works with `--cjs`, `--ts` and the optional middleware, except `--session`.
+
+### Web apps with a JSON API
+
+`--api` with a view engine, such as `--api --view=pug`, generates a web app that has a JSON API too:
+everything a web app has, and a `routes/api.js` router mounted at `/api`.
+
+```
+my-app
+├── app.js            # the web app, with JSON errors under /api
+├── routes/
+│   ├── api.js        # JSON routes: GET /api and GET /api/users
+│   ├── index.js      # the home page
+│   └── users.js
+├── views/
+└── ...
+```
+
+Every error of a request under `/api` is JSON, in the same shape as a JSON API's: the 404 of an
+unknown route, an error a route throws, and the errors of the middleware before the routes, such as a
+request body that is not valid JSON. Every other error renders the `error` view.
+
+With `--cors` and `--csrf`, you choose which routes they apply to:
+
+- `--cors-scope=api` (default) lets other origins call the API only, not read the pages;
+  `--cors-scope=all` lets them call the whole app.
+- `--csrf-scope=all` (default) requires the CSRF token under `/api` too, for an API your own pages
+  call; `--csrf-scope=pages` leaves the API out, for an API other clients call without the session
+  cookie.
+
+The wizard asks both.
+
+The view engine has to be given, as `--api` alone is a JSON API without views: use `--view=pug` for
+the default one. `--api` does not add an API to a `--no-view` app.
 
 ### Module formats
 
@@ -158,7 +191,8 @@ files with `--api`). Add more with:
 - `--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`
+- `--session` (not for JSON APIs without views): [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
@@ -221,15 +255,22 @@ support TypeScript 7 yet, these apps use TypeScript 6.
     -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
+                         (with --view, a web app with a JSON API at /api)
         --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
+        --cors-scope <scope>
+                         with --api and --view, the routes other origins can
+                         call (api|all) (defaults to api)
         --rate-limit     add express-rate-limit to limit requests per client
-        --session        add express-session for sessions (not with --api)
+        --session        add express-session for sessions (not with --api alone)
         --csrf           add CSRF protection for forms (needs --session)
+        --csrf-scope <scope>
+                         with --api and --view, the routes that need a CSRF
+                         token (all|pages) (defaults to all)
         --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
@@ -257,13 +298,14 @@ pug in place of jade, for Node.js 22.9 or newer. `--view=<engine>` replaces the
 ## Contributing
 
 ```bash
-$ npm install
-$ npm test       # generates, installs and runs apps for each option
-$ npm run lint
+$ pnpm install
+$ pnpm test      # generates, installs and runs apps for each option
+$ pnpm 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.
+This repository requires pnpm 11 or newer, as generated apps do by default, so
+[install pnpm](https://pnpm.io/installation) first; npm refuses to install it or run its scripts.
+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.

package/bin/express-cli.js

@@ -5,7 +5,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import readline from 'node:readline'
 import util from 'node:util'
-import { DEFAULT_PACKAGE_MANAGER, LOGGERS, PACKAGE_MANAGERS, VIEW_ENGINES, checkDestination, createAppName, mergeLines, planApp, scriptCommand } from '../lib/app.js'
+import { CORS_SCOPES, CSRF_SCOPES, DEFAULT_PACKAGE_MANAGER, LOGGERS, PACKAGE_MANAGERS, VIEW_ENGINES, checkDestination, createAppName, mergeLines, planApp, scriptCommand } from '../lib/app.js'
 import { CancelError } from '../lib/prompts.js'
 import { wizard } from '../lib/wizard.js'
 
@@ -19,7 +19,9 @@ const OPTIONS = {
   compression: { type: 'boolean' },
   cookies: { type: 'boolean' },
   cors: { type: 'boolean' },
+  'cors-scope': { type: 'string' },
   csrf: { type: 'boolean' },
+  'csrf-scope': { type: 'string' },
   docker: { type: 'boolean' },
   force: { type: 'boolean', short: 'f' },
   git: { type: 'boolean' },
@@ -283,6 +285,14 @@ function main (options, done) {
     usage()
     error('option `--pm <name>\' argument missing')
     done(1)
+  } else if (options.corsScope === '') {
+    usage()
+    error('option `--cors-scope <scope>\' argument missing')
+    done(1)
+  } else if (options.csrfScope === '') {
+    usage()
+    error('option `--csrf-scope <scope>\' argument missing')
+    done(1)
   } else {
     // Path
     const destinationPath = options._[0] || '.'
@@ -290,14 +300,9 @@ function main (options, done) {
     // App name
     const appName = createAppName(path.resolve(destinationPath)) || 'hello-world'
 
-    // A JSON API has no view engine
-    if (options.api) {
-      if (typeof options.view === 'string') {
-        usage()
-        error('option `--api\' cannot be used with `--view\'')
-        return done(1)
-      }
-
+    // A JSON API has no view engine, unless one is given with `--view`,
+    // for a web app with a JSON API
+    if (options.api && typeof options.view !== 'string') {
       options.view = false
     }
 
@@ -340,9 +345,9 @@ function main (options, done) {
     }
 
     // Sessions are for web apps, and CSRF protection needs them and views
-    if (options.session && options.api) {
+    if (options.session && options.api && !options.view) {
       usage()
-      error('option `--session\' cannot be used with `--api\'')
+      error('option `--session\' cannot be used with `--api\', unless `--view\' is given too')
       return done(1)
     }
 
@@ -358,6 +363,38 @@ function main (options, done) {
       return done(1)
     }
 
+    // Where CORS and CSRF protection apply is a choice only for a web app
+    // with a JSON API
+    const webApi = Boolean(options.api && options.view)
+
+    if (options.corsScope !== undefined) {
+      if (!CORS_SCOPES.includes(options.corsScope)) {
+        usage()
+        error('unsupported CORS scope `' + options.corsScope + "'")
+        return done(1)
+      }
+
+      if (!webApi || !options.cors) {
+        usage()
+        error('option `--cors-scope\' requires `--cors\', `--api\' and `--view\'')
+        return done(1)
+      }
+    }
+
+    if (options.csrfScope !== undefined) {
+      if (!CSRF_SCOPES.includes(options.csrfScope)) {
+        usage()
+        error('unsupported CSRF scope `' + options.csrfScope + "'")
+        return done(1)
+      }
+
+      if (!webApi || !options.csrf) {
+        usage()
+        error('option `--csrf-scope\' requires `--csrf\', `--api\' and `--view\'')
+        return done(1)
+      }
+    }
+
     // Check the destination before writing anything
     const entries = planApp(appName, options)
     const { blockers, conflicts, leftovers } = checkDestination(destinationPath, entries)
@@ -446,6 +483,8 @@ function parseOptions (argv) {
   options.git = !options['no-git']
   options.keepConfig = Boolean(options['keep-config'])
   options.rateLimit = Boolean(options['rate-limit'])
+  options.corsScope = options['cors-scope']
+  options.csrfScope = options['csrf-scope']
   options.logger ??= 'morgan'
   options.pm ??= DEFAULT_PACKAGE_MANAGER
 
@@ -470,15 +509,22 @@ function usage () {
   console.log('    -v, --view <engine>  add view <engine> support (ejs|hbs|pug|twig) (defaults to pug)')
   console.log('        --no-view        use static html instead of view engine')
   console.log('        --api            generate a JSON API, without views or static files')
+  console.log('                         (with --view, a web app with a JSON API at /api)')
   console.log('        --cjs            generate CommonJS modules instead of ES modules')
   console.log('        --ts             generate TypeScript, run directly by Node.js')
   console.log('        --helmet         add helmet middleware for security headers')
   console.log('        --compression    add compression middleware for gzip/brotli responses')
   console.log('        --cookies        add cookie-parser middleware')
   console.log('        --cors           add cors middleware for cross-origin requests')
+  console.log('        --cors-scope <scope>')
+  console.log('                         with --api and --view, the routes other origins can')
+  console.log('                         call (api|all) (defaults to api)')
   console.log('        --rate-limit     add express-rate-limit to limit requests per client')
-  console.log('        --session        add express-session for sessions (not with --api)')
+  console.log('        --session        add express-session for sessions (not with --api alone)')
   console.log('        --csrf           add CSRF protection for forms (needs --session)')
+  console.log('        --csrf-scope <scope>')
+  console.log('                         with --api and --view, the routes that need a CSRF')
+  console.log('                         token (all|pages) (defaults to all)')
   console.log('        --uploads        add multer and an upload route at /uploads')
   console.log('        --logger <name>  request logger (morgan|pino) (defaults to morgan)')
   console.log('        --docker         add a Dockerfile for a production image')

package/lib/app.js

@@ -35,6 +35,11 @@ export const PACKAGE_MANAGERS = {
 
 export const DEFAULT_PACKAGE_MANAGER = 'pnpm'
 
+// where the CORS headers and the CSRF protection of a web app with a JSON
+// API apply, with the default first
+export const CORS_SCOPES = ['api', 'all']
+export const CSRF_SCOPES = ['all', 'pages']
+
 // views generated only with some options
 const OPTIONAL_VIEWS = { 'new-user': 'csrf', uploads: 'uploads' }
 
@@ -75,7 +80,7 @@ const TSCONFIG = {
 // not use: code in the other language, the other ESLint config, the pnpm
 // settings and the templates of other view engines
 const ALTERNATIVES = [
-  ...['app', 'bin/www', 'csrf', 'routes/index', 'routes/uploads', 'routes/users', 'test/app.test'].flatMap((file) => [file + '.js', file + '.ts']),
+  ...['app', 'bin/www', 'csrf', 'routes/api', 'routes/index', 'routes/uploads', 'routes/users', 'test/app.test'].flatMap((file) => [file + '.js', file + '.ts']),
   'eslint.config.js',
   'eslint.config.mjs',
   'pnpm-workspace.yaml',
@@ -117,13 +122,21 @@ export function planApp (name, options) {
   const esm = !options.cjs
   const dirname = esm ? 'import.meta.dirname' : '__dirname'
 
-  // App kind: a JSON API has no views or static files
-  const api = Boolean(options.api)
+  // App kind: a JSON API has no views or static files, and a web app with
+  // a view engine can have a JSON API too, under /api
+  const api = Boolean(options.api) && !options.view
+  const webApi = Boolean(options.api) && Boolean(options.view)
 
   // Sessions, and CSRF protection using them, are for web apps with views
   const session = Boolean(options.session) && !api
   const csrf = Boolean(options.csrf) && session && Boolean(options.view)
 
+  // In a web app with a JSON API, other origins can call only the API,
+  // unless the whole app is chosen, and CSRF protection covers the API,
+  // unless only the pages are chosen
+  const corsApi = webApi && options.corsScope !== 'all'
+  const csrfSkipApi = webApi && csrf && options.csrfScope === 'pages'
+
   // File uploads, with an upload form in apps with views
   const uploads = Boolean(options.uploads)
 
@@ -182,6 +195,7 @@ export function planApp (name, options) {
   }
 
   app.locals.dirname = dirname
+  app.locals.webApi = webApi
   app.locals.httpErrors = Boolean(options.view) || api
   app.locals.trustProxy = trustProxy
   app.locals.session = session
@@ -191,6 +205,8 @@ export function planApp (name, options) {
   test.locals.csrf = csrf
   test.locals.uploads = uploads
   test.locals.view = Boolean(options.view)
+  test.locals.webApi = webApi
+  test.locals.csrfSkipApi = csrfSkipApi
 
   // App modules
   app.locals.localModules = Object.create(null)
@@ -216,7 +232,7 @@ export function planApp (name, options) {
   // Cross-origin requests
   if (options.cors) {
     app.locals.modules.cors = 'cors'
-    app.locals.uses.push("cors({\n  // any origin, or only the comma-separated origins in CORS_ORIGIN\n  origin: process.env.CORS_ORIGIN?.split(',').map((origin) => origin.trim()) ?? '*'\n})")
+    app.locals.uses.push((corsApi ? "'/api', " : '') + "cors({\n  // any origin, or only the comma-separated origins in CORS_ORIGIN\n  origin: process.env.CORS_ORIGIN?.split(',').map((origin) => origin.trim()) ?? '*'\n})")
     pkg.dependencies.cors = VERSIONS.cors
   }
 
@@ -304,6 +320,16 @@ export function planApp (name, options) {
     pkg.dependencies['http-errors'] = VERSIONS['http-errors']
   }
 
+  // API router, for the JSON routes of a web app
+  if (webApi) {
+    const router = loadTemplate('app/routes/api.js')
+    router.locals.esm = esm
+    file('routes/api.' + ext, router.render())
+
+    app.locals.localModules.apiRouter = './routes/api.' + ext
+    app.locals.mounts.push({ path: '/api', code: 'apiRouter' })
+  }
+
   // Template support
   if (options.view) {
     const view = VIEW_ENGINES[options.view]
@@ -373,6 +399,7 @@ export function planApp (name, options) {
     const module = loadTemplate('app/csrf.js')
     module.locals.esm = esm
     module.locals.uploads = uploads
+    module.locals.skipApi = csrfSkipApi
     file('csrf.' + ext, module.render())
 
     app.locals.localModules.csrf = './csrf.' + ext
@@ -550,8 +577,7 @@ export function scriptCommand (pm, script) {
 
 export function mergeLines (existing, generated) {
   const have = new Set(existing.split(/\r?\n/).map((line) => line.trim()))
-  const missing = generated.split('\n')
-    .map((line) => line.trim())
+  const missing = [...new Set(generated.split('\n').map((line) => line.trim()))]
     .filter((line) => line && !line.startsWith('#') && !have.has(line))
 
   if (!missing.length) return existing

package/lib/wizard.js

@@ -47,14 +47,20 @@ export async function wizard (io) {
         initial: answers.kind,
         choices: [
           { label: 'Web app', value: 'web', hint: 'server-rendered views' },
-          { label: 'JSON API', value: 'api', hint: 'no views or static files' }
+          { label: 'JSON API', value: 'api', hint: 'no views or static files' },
+          { label: 'Web app with a JSON API', value: 'both', hint: 'under /api' }
         ]
       })
     },
     {
       name: 'view',
-      when: () => answers.kind === 'web',
-      ask: (step) => step.ask(select, { message: 'View engine', initial: answers.view, choices: VIEWS })
+      when: () => answers.kind !== 'api',
+      ask: (step) => step.ask(select, {
+        message: 'View engine',
+        initial: answers.view,
+        // the pages of a web app with a JSON API need a view engine
+        choices: answers.kind === 'both' ? VIEWS.filter((view) => view.value !== false) : VIEWS
+      })
     },
     {
       name: 'language',
@@ -80,16 +86,40 @@ export async function wizard (io) {
           { 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' }] : []),
+          ...(answers.kind !== 'api' ? [{ label: 'express-session', value: 'session', hint: 'req.session' }] : []),
           { label: 'multer', value: 'uploads', hint: 'file uploads at /uploads' }
         ]
       })
     },
+    {
+      name: 'corsScope',
+      when: () => answers.kind === 'both' && answers.middleware.includes('cors'),
+      ask: (step) => step.ask(select, {
+        message: 'Other origins can call',
+        initial: answers.corsScope,
+        choices: [
+          { label: 'The API only', value: 'api', hint: 'routes under /api' },
+          { label: 'The whole app', value: 'all', hint: 'the pages too' }
+        ]
+      })
+    },
     {
       name: 'csrf',
-      when: () => answers.kind === 'web' && answers.view !== false && answers.middleware.includes('session'),
+      when: () => answers.kind !== 'api' && answers.view !== false && answers.middleware.includes('session'),
       ask: (step) => step.ask(confirm, { message: 'Protect forms with CSRF tokens?', initial: answers.csrf ?? true })
     },
+    {
+      name: 'csrfScope',
+      when: () => answers.kind === 'both' && answers.middleware.includes('session') && answers.csrf === true,
+      ask: (step) => step.ask(select, {
+        message: 'CSRF tokens for the API',
+        initial: answers.csrfScope,
+        choices: [
+          { label: 'Required', value: 'all', hint: 'your pages call the API' },
+          { label: 'Not required', value: 'pages', hint: 'other clients call it, without the session cookie' }
+        ]
+      })
+    },
     {
       name: 'logger',
       ask: (step) => step.ask(select, {
@@ -305,18 +335,22 @@ function eraseText (io, printed) {
 
 function toOptions (answers) {
   const { directory, kind, language, middleware = [], extras = [] } = answers
-  const view = kind === 'web' ? answers.view : false
-  const session = kind === 'web' && middleware.includes('session')
+  const view = kind === 'api' ? false : answers.view
+  const session = kind !== 'api' && middleware.includes('session')
+  const csrf = session && view !== false && answers.csrf === true
 
   return {
     _: [directory.dir],
     '!': [],
-    api: kind === 'api',
+    api: kind !== 'web',
     cjs: language === 'cjs',
     compression: middleware.includes('compression'),
     cookies: middleware.includes('cookies'),
     cors: middleware.includes('cors'),
-    csrf: session && view !== false && answers.csrf === true,
+    // the choices of a web app with a JSON API
+    ...(kind === 'both' && middleware.includes('cors') && { corsScope: answers.corsScope ?? 'api' }),
+    csrf,
+    ...(kind === 'both' && csrf && { csrfScope: answers.csrfScope ?? 'all' }),
     docker: extras.includes('docker'),
     force: directory.force,
     git: answers.git,
@@ -345,7 +379,8 @@ export function toCommand (options) {
   const args = [pm, 'create', 'express-new@latest', quote(options._[0])]
   const flags = []
 
-  if (options.api) flags.push('--api')
+  // a JSON API has no view engine, unless one is given, the default included
+  if (options.api) flags.push('--api', ...(options.view ? ['--view=' + options.view] : []))
   else if (options.view === false) flags.push('--no-view')
   else if (options.view !== 'pug') flags.push('--view=' + options.view)
 
@@ -355,9 +390,11 @@ export function toCommand (options) {
   if (options.compression) flags.push('--compression')
   if (options.cookies) flags.push('--cookies')
   if (options.cors) flags.push('--cors')
+  if (options.corsScope === 'all') flags.push('--cors-scope=all')
   if (options.rateLimit) flags.push('--rate-limit')
   if (options.session) flags.push('--session')
   if (options.csrf) flags.push('--csrf')
+  if (options.csrfScope === 'pages') flags.push('--csrf-scope=pages')
   if (options.uploads) flags.push('--uploads')
   if (options.logger && options.logger !== 'morgan') flags.push('--logger=' + options.logger)
   if (options.docker) flags.push('--docker')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-express-new",
   "description": "Express 5 application generator: ESM, TypeScript and CommonJS app templates. A modern successor to express-generator.",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": "Michael Caines (https://github.com/w0244079)",
   "contributors": [
     "TJ Holowaychuk <tj@vision-media.ca>",
@@ -27,7 +27,10 @@
     "web",
     "api"
   ],
-  "repository": "github:w0244079/create-express-new",
+  "repository": {
+    "type": "git",
+    "url": "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",
@@ -41,6 +44,7 @@
   },
   "devDependencies": {
     "eslint": "^9.39.5",
+    "fast-check": "^4.10.2",
     "mocha": "^12.0.3",
     "neostandard": "^0.13.0",
     "supertest": "^7.3.0",
@@ -50,6 +54,13 @@
   "engines": {
     "node": ">=22.9"
   },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": ">=11",
+      "onFail": "error"
+    }
+  },
   "files": [
     "CHANGELOG.md",
     "LICENSE",
@@ -61,7 +72,6 @@
     "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"
+    "versions": "node scripts/versions.js"
   }
-}
+}

package/templates/app/app.js.ejs

@@ -84,7 +84,31 @@ app.use((req, res, next) => {
   next(createError(404));
 });
 
+<% if (webApi) { -%>
+// error handler for the API, responding with JSON to every error of a
+// request under /api, including those of the middleware above
+<% if (ts) { -%>
+app.use('/api', (err: HttpError, req: Request, res: Response, next: NextFunction) => {
+<% } else { -%>
+app.use('/api', (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 })
+  });
+});
+
+// error handler for the pages
+<% } else { -%>
 // error handler
+<% } -%>
 <% if (ts) { -%>
 app.use((err: HttpError, req: Request, res: Response, next: NextFunction) => {
 <% } else { -%>

package/templates/app/csrf.js.ejs

@@ -7,8 +7,17 @@ const { csrfSync } = require('csrf-sync');
 // CSRF protection for requests that change data, which must send the token
 // in a _csrf form field or an x-csrf-token header (GET is not checked)
 const csrf = csrfSync({
-  getTokenFromRequest: (req) => req.body?._csrf ?? req.get('x-csrf-token')<%- uploads ? ',' : '' %>
-<% if (uploads) { -%>
+  getTokenFromRequest: (req) => req.body?._csrf ?? req.get('x-csrf-token')<%- uploads || skipApi ? ',' : '' %>
+<% if (uploads && skipApi) { -%>
+  // uploads check the token themselves, as multer reads their form, and the
+  // API is not protected, so its routes must not trust the session cookie:
+  // authenticate them another way, such as a token in a header
+  skipCsrfProtection: (req) => req.path === '/uploads' || /^\/api(\/|$)/i.test(req.path)
+<% } else if (skipApi) { -%>
+  // the API is not protected, so its routes must not trust the session
+  // cookie: authenticate them another way, such as a token in a header
+  skipCsrfProtection: (req) => /^\/api(\/|$)/i.test(req.path)
+<% } else if (uploads) { -%>
   // uploads check the token themselves, as multer reads their form
   skipCsrfProtection: (req) => req.path === '/uploads'
 <% } -%>

package/templates/app/routes/api.js.ejs

@@ -0,0 +1,26 @@
+<% if (esm) { -%>
+import express from 'express';
+<% } else { -%>
+const express = require('express');
+<% } -%>
+
+const router = express.Router();
+
+// JSON routes, mounted at /api: errors under /api, such as the 404 of a
+// route that is not here, respond with JSON too (see the app's error handlers)
+
+/* GET the API's welcome message. */
+router.get('/', (req, res) => {
+  res.json({ message: 'Welcome to Express' });
+});
+
+/* GET users listing. */
+router.get('/users', (req, res) => {
+  res.json([]);
+});
+
+<% if (esm) { -%>
+export default router;
+<% } else { -%>
+module.exports = router;
+<% } -%>

package/templates/app/test/app.test.js.ejs

@@ -194,6 +194,54 @@ describe('app', () => {
   it('responds with 404 for unknown routes', async () => {
     const res = await fetch(`${baseUrl}/does-not-exist`);
     assert.strictEqual(res.status, 404);
+<% if (webApi) { -%>
+    assert.match(res.headers.get('content-type') ?? '', /text\/html/);
+<% } -%>
+  });
+<% if (webApi) { -%>
+
+  it('responds to GET /api', async () => {
+    const res = await fetch(`${baseUrl}/api`);
+    assert.strictEqual(res.status, 200);
+    assert.deepStrictEqual(await res.json(), { message: 'Welcome to Express' });
   });
+
+  it('responds to GET /api/users', async () => {
+    const res = await fetch(`${baseUrl}/api/users`);
+    assert.strictEqual(res.status, 200);
+    assert.deepStrictEqual(await res.json(), []);
+  });
+
+  it('responds with a JSON 404 for unknown API routes', async () => {
+    const res = await fetch(`${baseUrl}/api/does-not-exist`);
+    assert.strictEqual(res.status, 404);
+    assert.match(res.headers.get('content-type') ?? '', /application\/json/);
+    assert.strictEqual((await res.json()).error, 'Not Found');
+  });
+
+  it('responds with a JSON error for an invalid API request body', async () => {
+    const res = await fetch(`${baseUrl}/api/users`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: '{'
+    });
+    assert.strictEqual(res.status, 400);
+    assert.match(res.headers.get('content-type') ?? '', /application\/json/);
+  });
+<% if (csrf && csrfSkipApi) { -%>
+
+  it('does not ask API posts for a CSRF token', async () => {
+    const res = await fetch(`${baseUrl}/api/does-not-exist`, { method: 'POST' });
+    assert.strictEqual(res.status, 404);
+  });
+<% } else if (csrf) { -%>
+
+  it('rejects API posts without a CSRF token, with a JSON error', async () => {
+    const res = await fetch(`${baseUrl}/api/users`, { method: 'POST' });
+    assert.strictEqual(res.status, 403);
+    assert.match(res.headers.get('content-type') ?? '', /application\/json/);
+  });
+<% } -%>
+<% } -%>
 });
 <% } -%>