create-express-new 0.0.0-stage → 1.1.0

package/templates/app/csrf.js.ejs

@@ -0,0 +1,21 @@
+<% if (esm) { -%>
+import { csrfSync } from 'csrf-sync';
+<% } else { -%>
+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) { -%>
+  // uploads check the token themselves, as multer reads their form
+  skipCsrfProtection: (req) => req.path === '/uploads'
+<% } -%>
+});
+
+<% if (esm) { -%>
+export default csrf;
+<% } else { -%>
+module.exports = csrf;
+<% } -%>

package/templates/app/dockerignore

@@ -0,0 +1,15 @@
+# Dependencies are installed in the image
+node_modules
+
+# Environment variables are set by the container platform
+.env
+.env.*
+
+# Not needed to run the app
+.git
+.gitignore
+coverage
+test
+Dockerfile
+.dockerignore
+*.log

package/templates/app/env.example.ejs

@@ -0,0 +1,40 @@
+# Environment variables for local development.
+#
+# Copy this file to .env, which `<%- start %>` and `<%- dev %>` load automatically.
+# Variables already set in the environment take precedence over .env.
+# Do not commit .env.
+
+PORT=3000
+
+# Set to production when you deploy
+# NODE_ENV=production
+<% if (cors) { -%>
+
+# Comma-separated origins allowed to call the app from a browser
+# (defaults to any origin)
+# CORS_ORIGIN=https://example.com,https://admin.example.com
+<% } -%>
+<% if (trustProxy) { -%>
+
+# Behind a load balancer or other proxy, the number of proxies (or their
+# addresses), so the app sees each client's IP address and protocol
+# TRUST_PROXY=1
+<% } -%>
+<% if (rateLimit) { -%>
+
+# Requests each client may make in each window of milliseconds
+# (defaults to 100 every 15 minutes)
+# RATE_LIMIT_MAX=100
+# RATE_LIMIT_WINDOW_MS=900000
+<% } -%>
+<% if (session) { -%>
+
+# Long random secret that signs the session cookie, required in production,
+# such as the output of: node -e "console.log(crypto.randomBytes(32).toString('hex'))"
+# SESSION_SECRET=
+<% } -%>
+<% if (uploads) { -%>
+
+# Largest file that can be uploaded, in bytes (defaults to 5 MB)
+# UPLOAD_MAX_SIZE=5242880
+<% } -%>

package/templates/app/eslint.config.js.ejs

@@ -0,0 +1,28 @@
+import js from '@eslint/js';
+import { defineConfig } from 'eslint/config';
+import globals from 'globals';
+<% if (ts) { -%>
+import tseslint from 'typescript-eslint';
+<% } -%>
+
+export default defineConfig([
+  js.configs.recommended,
+<% if (ts) { -%>
+  tseslint.configs.recommended,
+<% } -%>
+<% if (!esm) { -%>
+  {
+    files: ['**/*.js'],
+    languageOptions: { sourceType: 'commonjs' }
+  },
+<% } -%>
+  {
+    languageOptions: {
+      globals: globals.node
+    },
+    rules: {
+      // Express error handlers need all four arguments, even when next is unused
+      '<%- ts ? '@typescript-eslint/' : '' %>no-unused-vars': ['error', { argsIgnorePattern: '^next$' }]
+    }
+  }
+]);

package/templates/app/gitignore

@@ -0,0 +1,22 @@
+# Dependencies
+node_modules/
+
+# Environment variables, except the example
+.env
+.env.*
+!.env.example
+
+# Logs
+logs/
+*.log
+npm-debug.log*
+
+# Test coverage
+coverage/
+
+# TypeScript
+*.tsbuildinfo
+
+# Operating system files
+.DS_Store
+Thumbs.db

package/templates/app/npmrc

@@ -0,0 +1,8 @@
+# npm settings that protect installs from compromised packages.
+# npm 12 and newer, which this app requires in package.json, also refuses
+# dependencies from git and skips the install scripts of dependencies unless
+# they are approved with `npm approve-scripts`.
+
+# Wait 3 days before installing a newly published version, so a compromised
+# release can be found and removed from the registry first.
+min-release-age=3

package/templates/app/pnpm-workspace.yaml

@@ -0,0 +1,24 @@
+# pnpm settings that protect installs from compromised packages.
+# https://pnpm.io/supply-chain-security
+
+# Wait 3 days (in minutes) before installing a newly published version, so a
+# compromised release can be found and removed from the registry first.
+minimumReleaseAge: 4320
+
+# Fail when a dependency wants to run an install script, instead of skipping
+# it. None of this app's dependencies need one; approve a package you trust
+# with `pnpm approve-builds`.
+strictDepBuilds: true
+
+# Dependencies of dependencies must come from the registry, not git or a URL.
+blockExoticSubdeps: true
+
+# Fail when a version was published with weaker proof of where it came from
+# than an earlier version of the package, a sign of a stolen account. Versions
+# over a year old (in minutes) are not checked.
+trustPolicy: no-downgrade
+trustPolicyIgnoreAfter: 525600
+
+# Run the pnpm version recorded in pnpm-lock.yaml, downloading it when another
+# version is installed, so everyone installs with the same pnpm.
+pmOnFail: download

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

@@ -0,0 +1,22 @@
+<% if (esm) { -%>
+import express from 'express';
+<% } else { -%>
+const express = require('express');
+<% } -%>
+
+const router = express.Router();
+
+/* GET home page. */
+router.get('/', (req, res) => {
+<% if (api) { -%>
+  res.json({ message: 'Welcome to Express' });
+<% } else { -%>
+  res.render('index', { title: 'Express' });
+<% } -%>
+});
+
+<% if (esm) { -%>
+export default router;
+<% } else { -%>
+module.exports = router;
+<% } -%>

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

@@ -0,0 +1,94 @@
+<% if (esm) { -%>
+import express from 'express';
+<% if (ts) { -%>
+import type { NextFunction, Request, Response } from 'express';
+<% } -%>
+import createError from 'http-errors';
+import multer from 'multer';
+import path from 'node:path';
+<% if (csrf) { -%>
+import csrf from '../csrf.<%- ext %>';
+<% } -%>
+<% } else { -%>
+const express = require('express');
+const createError = require('http-errors');
+const multer = require('multer');
+const path = require('node:path');
+<% if (csrf) { -%>
+const csrf = require('../csrf.js');
+<% } -%>
+<% } -%>
+
+const router = express.Router();
+
+// file types to accept, as sent by the client, so check a file's contents
+// too before trusting it
+const TYPES = ['application/pdf', 'image/gif', 'image/jpeg', 'image/png', 'image/webp', 'text/plain'];
+
+// files are saved in uploads/ under random names, never the name the client
+// sends, and are not served as static files, where they could run scripts
+const upload = multer({
+  dest: path.join(<%- dirname %>, '..', 'uploads'),
+  limits: {
+    // bytes per file, 5 MB unless set
+    fileSize: Number(process.env.UPLOAD_MAX_SIZE) || 5 * 1024 * 1024,
+    files: 1
+  },
+  fileFilter: (req, file, cb) => {
+<% if (csrf) { -%>
+    // check the CSRF token, from the _csrf field before the file, so
+    // nothing is saved without it
+    if (!csrf.isRequestValid(req)) return cb(csrf.invalidCsrfTokenError);
+<% } -%>
+    if (!TYPES.includes(file.mimetype)) return cb(createError(415, 'Unsupported file type'));
+    cb(null, true);
+  }
+});
+
+<% if (view) { -%>
+/* GET the upload form. */
+router.get('/', (req, res) => {
+  res.render('uploads', { title: 'Upload a file', uploaded: req.query.uploaded });
+});
+
+<% } -%>
+/* POST a file in the `file` field. */
+router.post('/', upload.single('file'), (req, res, next) => {
+<% if (csrf) { -%>
+  // without a file, the CSRF token is not checked yet
+  if (!csrf.isRequestValid(req)) return next(csrf.invalidCsrfTokenError);
+<% } -%>
+  if (!req.file) return next(createError(400, 'Choose a file to upload'));
+
+<% if (view) { -%>
+  // redirect, so refreshing the page does not upload again
+  res.redirect(303, `/uploads?uploaded=${encodeURIComponent(req.file.originalname)}`);
+<% } else { -%>
+  res.status(201).json({
+    // the file's name in uploads/
+    id: req.file.filename,
+    name: req.file.originalname,
+    type: req.file.mimetype,
+    size: req.file.size
+  });
+<% } -%>
+});
+
+// multer's errors, such as a file over the size limit, are client errors
+<% if (ts) { -%>
+router.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+<% } else { -%>
+router.use((err, req, res, next) => {
+<% } -%>
+  if (err instanceof multer.MulterError) {
+    next(createError(err.code === 'LIMIT_FILE_SIZE' ? 413 : 400, err.message));
+  } else {
+    next(err);
+  }
+});
+
+<% if (esm) { -%>
+export default router;
+<% } else { -%>
+module.exports = router;
+<% } -%>

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

@@ -0,0 +1,42 @@
+<% if (esm) { -%>
+import express from 'express';
+<% } else { -%>
+const express = require('express');
+<% } -%>
+
+const router = express.Router();
+
+/* GET users listing. */
+router.get('/', (req, res) => {
+<% if (api) { -%>
+  res.json([]);
+<% } else { -%>
+  res.send('respond with a resource');
+<% } -%>
+});
+
+<% if (form) { -%>
+/* GET the new user form. */
+router.get('/new', (req, res) => {
+  res.render('new-user', { title: 'New user', added: req.query.added });
+});
+
+/* POST the new user form, after the app checks its CSRF token. */
+router.post('/new', (req, res) => {
+  const name = String(req.body?.name ?? '').trim();
+
+  if (!name) {
+    res.status(400).render('new-user', { title: 'New user', error: 'Enter a name' });
+    return;
+  }
+
+  // save the user here, then redirect, so refreshing the page does not post again
+  res.redirect(303, `/users/new?added=${encodeURIComponent(name)}`);
+});
+
+<% } -%>
+<% if (esm) { -%>
+export default router;
+<% } else { -%>
+module.exports = router;
+<% } -%>

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

@@ -0,0 +1,199 @@
+<% if (esm) { -%>
+import assert from 'node:assert';
+import { once } from 'node:events';
+<% if (uploads) { -%>
+import fs from 'node:fs';
+<% } -%>
+<% if (ts) { -%>
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+<% } -%>
+import { after, before, describe, it } from 'node:test';
+<% if (uploads) { -%>
+import path from 'node:path';
+<% } -%>
+import app from '../app.<%- ext %>';
+<% } else { -%>
+const assert = require('node:assert');
+const { once } = require('node:events');
+<% if (uploads) { -%>
+const fs = require('node:fs');
+const path = require('node:path');
+<% } -%>
+const { after, before, describe, it } = require('node:test');
+const app = require('../app.js');
+<% } -%>
+
+// skip request logs while testing (see app.<%- ext %>)
+process.env.NODE_ENV = 'test';
+
+describe('app', () => {
+<% if (ts) { -%>
+  let server: Server;
+  let baseUrl: string;
+<% } else { -%>
+  let server;
+  let baseUrl;
+<% } -%>
+
+  before(async () => {
+    // listen on a random free port
+    server = app.listen(0);
+    await once(server, 'listening');
+<% if (ts) { -%>
+    baseUrl = `http://localhost:${(server.address() as AddressInfo).port}`;
+<% } else { -%>
+    baseUrl = `http://localhost:${server.address().port}`;
+<% } -%>
+  });
+
+  after(() => {
+    server.close();
+  });
+<% if (csrf) { -%>
+
+  // a session cookie and its CSRF token, from a page with a form
+<% if (ts) { -%>
+  async function csrfSession(url: string) {
+<% } else { -%>
+  async function csrfSession(url) {
+<% } -%>
+    const res = await fetch(url);
+    const cookie = res.headers.getSetCookie().map((header) => header.split(';')[0]).join('; ');
+    const token = /<meta name="csrf-token" content="([^"]+)">/.exec(await res.text())?.[1] ?? '';
+    return { cookie, token };
+  }
+<% } -%>
+
+  it('responds to GET /health', async () => {
+    const res = await fetch(`${baseUrl}/health`);
+    assert.strictEqual(res.status, 200);
+    assert.deepStrictEqual(await res.json(), { status: 'ok' });
+  });
+
+<% if (rateLimit) { -%>
+  it('sends rate limit headers', async () => {
+    const res = await fetch(`${baseUrl}/`);
+    assert.ok(res.headers.has('ratelimit-policy'));
+  });
+
+<% } -%>
+<% if (csrf) { -%>
+  it('rejects posts without a CSRF token', async () => {
+    const res = await fetch(`${baseUrl}/users/new`, { method: 'POST', body: new URLSearchParams({ name: 'Ada' }) });
+    assert.strictEqual(res.status, 403);
+  });
+
+  it('adds a user with the form and its CSRF token', async () => {
+    const { cookie, token } = await csrfSession(`${baseUrl}/users/new`);
+    const res = await fetch(`${baseUrl}/users/new`, {
+      method: 'POST',
+      headers: { cookie },
+      body: new URLSearchParams({ _csrf: token, name: 'Ada' }),
+      redirect: 'manual'
+    });
+    assert.strictEqual(res.status, 303);
+    assert.strictEqual(res.headers.get('location'), '/users/new?added=Ada');
+  });
+
+  it('asks again for a user without a name', async () => {
+    const { cookie, token } = await csrfSession(`${baseUrl}/users/new`);
+    const res = await fetch(`${baseUrl}/users/new`, {
+      method: 'POST',
+      headers: { cookie },
+      body: new URLSearchParams({ _csrf: token, name: ' ' })
+    });
+    assert.strictEqual(res.status, 400);
+    assert.match(await res.text(), /Enter a name/);
+  });
+
+<% } -%>
+<% if (uploads) { -%>
+  it('uploads a file', async () => {
+    const uploads = path.join(<%- esm ? 'import.meta.dirname' : '__dirname' %>, '..', 'uploads');
+    const existing = new Set(fs.readdirSync(uploads));
+<% if (csrf) { -%>
+    const { cookie, token } = await csrfSession(`${baseUrl}/uploads`);
+<% } -%>
+    const body = new FormData();
+<% if (csrf) { -%>
+    // the token comes before the file, so it is checked before saving
+    body.append('_csrf', token);
+<% } -%>
+    body.append('file', new Blob(['hello'], { type: 'text/plain' }), 'hello.txt');
+
+<% if (csrf) { -%>
+    const res = await fetch(`${baseUrl}/uploads`, { method: 'POST', headers: { cookie }, body, redirect: 'manual' });
+<% } else { -%>
+    const res = await fetch(`${baseUrl}/uploads`, { method: 'POST', body, redirect: 'manual' });
+<% } -%>
+<% if (view) { -%>
+    assert.strictEqual(res.status, 303);
+    assert.strictEqual(res.headers.get('location'), '/uploads?uploaded=hello.txt');
+<% } else { -%>
+    assert.strictEqual(res.status, 201);
+    assert.strictEqual((await res.json()).name, 'hello.txt');
+<% } -%>
+
+    // remove the uploaded file
+    const added = fs.readdirSync(uploads).filter((file) => !existing.has(file));
+    assert.strictEqual(added.length, 1);
+    for (const file of added) fs.rmSync(path.join(uploads, file));
+  });
+
+  it('rejects unsupported file types', async () => {
+<% if (csrf) { -%>
+    const { cookie, token } = await csrfSession(`${baseUrl}/uploads`);
+<% } -%>
+    const body = new FormData();
+<% if (csrf) { -%>
+    body.append('_csrf', token);
+<% } -%>
+    body.append('file', new Blob(['<html>'], { type: 'text/html' }), 'page.html');
+
+<% if (csrf) { -%>
+    const res = await fetch(`${baseUrl}/uploads`, { method: 'POST', headers: { cookie }, body });
+<% } else { -%>
+    const res = await fetch(`${baseUrl}/uploads`, { method: 'POST', body });
+<% } -%>
+    assert.strictEqual(res.status, 415);
+  });
+
+<% } -%><% if (api) { -%>
+  it('responds to GET /', async () => {
+    const res = await fetch(`${baseUrl}/`);
+    assert.strictEqual(res.status, 200);
+    assert.deepStrictEqual(await res.json(), { message: 'Welcome to Express' });
+  });
+
+  it('responds to GET /users', async () => {
+    const res = await fetch(`${baseUrl}/users`);
+    assert.strictEqual(res.status, 200);
+    assert.deepStrictEqual(await res.json(), []);
+  });
+
+  it('responds with a JSON 404 for unknown routes', async () => {
+    const res = await fetch(`${baseUrl}/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');
+  });
+});
+<% } else { -%>
+  it('responds to GET /', async () => {
+    const res = await fetch(`${baseUrl}/`);
+    assert.strictEqual(res.status, 200);
+  });
+
+  it('responds to GET /users', async () => {
+    const res = await fetch(`${baseUrl}/users`);
+    assert.strictEqual(res.status, 200);
+    assert.strictEqual(await res.text(), 'respond with a resource');
+  });
+
+  it('responds with 404 for unknown routes', async () => {
+    const res = await fetch(`${baseUrl}/does-not-exist`);
+    assert.strictEqual(res.status, 404);
+  });
+});
+<% } -%>

package/templates/app/www.js.ejs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+<% if (esm) { -%>
+import app from '../app.<%- ext %>';
+<% } else { -%>
+const app = require('../app.js');
+<% } -%>
+
+const port = process.env.PORT || 3000;
+
+const server = app.listen(port, (err) => {
+  if (err) {
+    // handle specific listen errors with friendly messages
+<% if (ts) { -%>
+    switch ((err as NodeJS.ErrnoException).code) {
+<% } else { -%>
+    switch (err.code) {
+<% } -%>
+      case 'EACCES':
+        console.error(`Port ${port} requires elevated privileges`);
+        process.exit(1);
+        break;
+      case 'EADDRINUSE':
+        console.error(`Port ${port} is already in use`);
+        process.exit(1);
+        break;
+      default:
+        throw err;
+    }
+  }
+
+  console.log(`Listening on port ${port}`);
+});
+
+// close the server gracefully when asked to stop
+<% if (ts) { -%>
+function shutdown(signal: NodeJS.Signals) {
+<% } else { -%>
+function shutdown(signal) {
+<% } -%>
+  console.log(`${signal} received, shutting down`);
+  server.close(() => process.exit(0));
+}
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/templates/public/index.html

@@ -0,0 +1,13 @@
+<html>
+
+<head>
+  <title>Express</title>
+  <link rel="stylesheet" href="/stylesheets/style.css">
+</head>
+
+<body>
+  <h1>Express</h1>
+  <p>Welcome to Express</p>
+</body>
+
+</html>

package/templates/public/stylesheets/style.css

@@ -0,0 +1,8 @@
+body {
+  padding: 50px;
+  font: 14px "Lucida Grande", Helvetica, Arial, sans-serif;
+}
+
+a {
+  color: #00B7FF;
+}

package/templates/versions.json

@@ -0,0 +1,49 @@
+{
+  "versions": {
+    "@eslint/js": "^10.0.1",
+    "@types/compression": "^1.8.1",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/express-session": "^1.19.0",
+    "@types/http-errors": "^2.0.5",
+    "@types/morgan": "^1.9.10",
+    "@types/multer": "^2.3.0",
+    "@types/node": "^22.20.5",
+    "compression": "^1.8.2",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "csrf-sync": "^4.2.1",
+    "ejs": "^6.0.1",
+    "eslint": "^10.12.0",
+    "express": "^5.2.1",
+    "express-rate-limit": "^8.7.0",
+    "express-session": "^1.19.0",
+    "globals": "^17.13.0",
+    "hbs": "^4.3.1",
+    "helmet": "^8.3.0",
+    "http-errors": "^2.0.1",
+    "morgan": "^1.12.1",
+    "multer": "^2.4.0",
+    "npm": "^12.2.0",
+    "pino-http": "^11.0.0",
+    "pino-pretty": "^13.1.3",
+    "pnpm": "^12.9.1",
+    "pug": "^3.0.4",
+    "twig": "^3.0.0",
+    "typescript": "^7.0.2",
+    "typescript-eslint": "^8.71.0",
+    "typescript@6": "^6.0.3"
+  },
+  "hold": {
+    "@types/node": "kept on the major of the minimum supported Node.js version (22)",
+    "typescript@6": {
+      "reason": "used with --ts --lint until typescript-eslint supports TypeScript 7",
+      "until": {
+        "package": "typescript-eslint",
+        "peer": "typescript",
+        "supports": "7.0.0"
+      }
+    }
+  }
+}

package/templates/views/error.ejs

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= title %></title>
+    <link rel='stylesheet' href='/stylesheets/style.css' />
+  </head>
+  <body>
+    <h1><%= message %></h1>
+    <h2><%= status %></h2>
+    <pre><%= error.stack %></pre>
+  </body>
+</html>

package/templates/views/error.hbs

@@ -0,0 +1,3 @@
+<h1>{{message}}</h1>
+<h2>{{status}}</h2>
+<pre>{{error.stack}}</pre>

package/templates/views/error.pug

@@ -0,0 +1,6 @@
+extends layout
+
+block content
+  h1= message
+  h2= status
+  pre #{error.stack}

package/templates/views/error.twig

@@ -0,0 +1,7 @@
+{% extends 'layout.twig' %}
+
+{% block body %}
+  <h1>{{message|e}}</h1>
+  <h2>{{status}}</h2>
+  <pre>{{error.stack|e}}</pre>
+{% endblock %}