Skip to content

fix: make generated projects build, ship and work with pnpm - #1

Merged
SibilSoren merged 4 commits into
mainfrom
fix/generated-project-builds
Nov 9, 2026
Merged

SibilSoren merged 4 commits into
mainfrom
fix/generated-project-builds

Conversation

@SibilSoren

Copy link
Copy Markdown
Owner

Description

I installed 1.0.0 from npm and used it the way three different people would: someone building their first API, a senior engineer checking whether it's production-ready, and a team lead setting it up with pnpm. The first few minutes are fine, but a project generated today can't be built or shipped:

  • npm run build fails with 6 TypeScript errors on a fresh project. The dependency ranges moved on since June.
  • The Docker image can't be built: the build stage hits those errors, and the production stage runs husky's prepare script without husky installed (exit 127).
  • In production Swagger lists no routes, because it reads src/, which isn't in the build.
  • validate(schema, 'query'), the usage shown in its own comment, returns a 500 on Express 5.
  • --package-manager pnpm fails on current pnpm, and the CLI hides the reason.

This PR fixes those and adds CI that would have caught them.

Type of Change

  • 🐛 Bug fix
  • ✨ New feature
  • 📝 Documentation update
  • 🔧 Refactor / chore
  • 💥 Breaking change (Node 22.12+ is now required; Node 20 is end of life)

Changes Made

Template

  • Dependencies updated (Zod 4 fixes a high-severity advisory). dotenv replaced by process.loadEnvFile().
  • Dockerfile on Node 24 with --ignore-scripts, plus .dockerignore.
  • Swagger reads route docs relative to its own file, so it works from src/ and dist/.
  • Query validation works on Express 5. Malformed JSON gets 400 and oversized bodies 413.
  • The pre-commit hook exists now (husky was installed with no hook).
  • /api/health hides memory and environment in production. Request logs are one line each.
  • New tests for validation, error handling, Swagger and the production health response (12 tests, up from 4).

CLI

  • git init before install so husky sets up its hook; the initial commit comes last and includes the lockfile.
  • pnpm: allow esbuild's build script (pnpm 10+ blocks it), pin the pnpm version for corepack, and use pnpm in the Dockerfile and README.
  • A failed install prints the package manager's error. Next steps use the chosen package manager.
  • --package-manager only accepts npm or pnpm. yarn was offered by the wizard but the Dockerfile never supported it.

CI

  • Scaffolds with npm and pnpm on Node 22, 24 and 26, then runs typecheck, build, tests with coverage, lint and format check, boots the production build and checks health, Swagger and the 400 for bad JSON.
  • Builds and runs the Docker image for npm and pnpm.
  • Runs weekly as well, since the template can break without any change to this repo.

The wizard's Gatekeeper and Prisma options still have their own problems. They're for a separate PR before the next release.

Testing

  • I've tested the CLI tool locally (npx tsx src/index.ts test-project)
  • The generated project boots successfully (npm run dev)
  • The generated project's tests pass (npm test)
  • I've run npm run lint with no errors

Locally on Node 26 with npm 11.20 and pnpm 12.16, for both package managers: typecheck, build, test, test:coverage, lint and format:check pass on a freshly generated project. The production build was started from a folder with only dist/ and production dependencies, the same as the Docker image. The Docker image itself is only built by the new CI jobs.

Screenshots / Logs

Production build, before and after:

before: swagger "paths": {}            bad JSON -> 500   npm ci --omit=dev -> exit 127 (husky)
after:  swagger lists "/api/health"    bad JSON -> 400   npm ci --omit=dev --ignore-scripts -> ok

Checklist

  • My code follows the project's code style
  • I've updated documentation if needed
  • I've added an entry to CHANGELOG.md (if user-facing change)

A project generated today failed `npm run build` with TypeScript errors,
because the dependency ranges had moved on. Docker failed too: the
production stage ran husky's prepare script without husky installed.

- Update dependencies (Zod 4, Express 5.3, Pino 10, ESLint 10, Vitest 5,
  TypeScript 6.0) and drop dotenv for process.loadEnvFile()
- Build Docker images on Node 24 with --ignore-scripts, add .dockerignore
- Read Swagger docs relative to the config file so production lists routes
- Fix validate(schema, 'query') on Express 5, where req.query is a getter
- Return 400 for malformed JSON and 413 for oversized bodies, not 500
- Add the missing pre-commit hook and @vitest/coverage-v8
- Hide memory and environment from /api/health in production
- One log line per request instead of every header
- Tests for validation, error handling, Swagger and production health
- Run git init before installing so husky can set up its hook, and make
  the initial commit last so it includes the lockfile
- pnpm 10+ blocks dependency build scripts and newer versions fail the
  install. Allow esbuild's, pin the pnpm version for corepack, and switch
  the Dockerfile and README to pnpm
- Print the package manager's output when an install fails
- Show next steps for the chosen package manager
- Reject unknown --package-manager values and drop yarn, which the
  Dockerfile never supported
- Read the CLI version from package.json
CI only scaffolded a project and ran its tests, so a template that no longer built went unnoticed. It now builds, lints and boots the production build on Node 22, 24 and 26, builds the Docker image, and runs weekly to catch dependency changes.
Node 20 reached end of life in April 2026. Changelog entry for the fixes.
@SibilSoren
SibilSoren merged commit f530eeb into main Nov 9, 2026
12 checks passed
@SibilSoren
SibilSoren deleted the fix/generated-project-builds branch November 9, 2026 07:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant