---
name: nodejs-express-api
description: "Scaffold REST APIs with Express 5, Zod validation, JWT auth, and OpenAPI docs. Builds production-grade Node.js REST APIs: Express 5 routers, Zod request validation, JWT authentication, rate limiting, error handling middleware, and auto-generated OpenAPI/Swagger docs."
license: MIT
---

# 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

```bash
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:

```js
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.