Node.js Express API Builder

Scaffold production-grade REST APIs on Express 5 with request validation, JWT auth, rate limiting, structured error handling, and live OpenAPI docs wired in from the first commit. This skill is for backend developers who want a sane, typed starting point instead of copy-pasting boilerplate from old projects, and who care about getting validation and auth right rather than bolting them on later.

When to use it

• You're starting a new service and want routers, middleware, and docs laid out consistently.
• You have an existing Express app and want to add a validated, documented endpoint without hand-writing the Zod schema, route handler, and Swagger entry separately.
• You need JWT-protected routes plus per-route rate limits and a uniform error response shape.

What it does

The skill generates an Express 5 app using the native async router (Express 5 forwards rejected promises to next(), so handlers can throw). Request bodies, params, and queries are validated with Zod schemas through a validate(schema) middleware that returns 400 with field-level issues on failure. Auth is handled by an authenticate middleware built on jsonwebtoken (jwt.sign / jwt.verify), reading a Bearer token and attaching the decoded payload to req.user. Rate limiting uses express-rate-limit, applied globally or per-router. A terminal error-handling middleware (the 4-arg (err, req, res, next) signature) normalizes thrown errors into a consistent JSON envelope. OpenAPI 3 specs are derived from the Zod schemas (via zod-to-openapi) and served through swagger-ui-express at /docs.

Usage example

curl -fsSL --create-dirs -o ~/.claude/skills/nodejs-express-api/SKILL.md https://claudeskil.com/skills/nodejs-express-api/SKILL.md
# then, inside your project:
claude "scaffold a users API with signup, login, and a protected GET /me"

Generated route shape:

router.post(
  "/login",
  validate(loginSchema),          // Zod: { email, password }
  loginHandler                    // issues jwt.sign({ sub: user.id })
);
router.get("/me", authenticate, getMeHandler); // 401 if no/!valid token

Tips & gotchas

• Express 5 path syntax changed. Wildcards now require names (/*splat, not /*), and optional params use {:id} style. The skill emits v5-compatible paths — don't paste v4 routes in verbatim.
• Set JWT_SECRET before running. Tokens fail verification silently into a 401 if the secret is missing; the scaffold reads it from process.env with no insecure fallback.
• Validate req.query carefully — in Express 5 it's a getter and effectively read-only, so coerce with Zod (z.coerce.number()) rather than mutating it in place.
• Mount the error middleware last, after all routers, or thrown errors bypass it and return Express's default HTML stack trace.

FAQ

Does it use TypeScript or JavaScript? Either. It defaults to TypeScript (Zod infers handler types via z.infer), but can emit JS with JSDoc types if your project has no tsconfig.json.

Is the OpenAPI spec hand-maintained? No — it's generated from the same Zod schemas used for validation, so docs and runtime checks can't drift apart.

Can I add it to an existing app? Yes. Point it at your app.js/index.ts and it adds routers and middleware without overwriting your existing setup.