code-quest: Skill for Claude Code

Express Server Skill

Stack: Express 4.x, TypeScript, ESM ("type": "module"), InversifyJS DI, Socket.IO, cors, helmet. The server is a thin HTTP layer — business logic lives in injected services, not in route files.

---

Project Structure

src/
  server/
    app.ts           # Express factory — creates and configures app, no listen()
    server.ts        # Entry point — binds port, handles SIGTERM
    routes/          # One file per resource, returns express.Router
    middleware/      # Custom middleware (auth, logging, validation)
    errors/          # AppError class, error handler middleware

---

Middleware Ordering

Register in this exact order — order is critical:

app.use(helmet());                    // 1. Security headers — first
app.use(cors(corsOptions));           // 2. CORS — before body parsing
app.use(express.json({ limit: '1mb' })); // 3. Body parsers
app.use(rateLimiter);                 // 4. Rate limiting
app.use('/static', express.static(staticDir, { maxAge: '1d' })); // 5. Static
app.use('/health', healthRouter);     // 6. Health — no auth needed
app.use('/api', apiRouter);           // 7. App routes
app.use(errorHandler);                // 8. Error handler — always last

---

Async Error Handling (Express 4)

Express 4 does not catch async errors automatically. Wrap handlers or use express-async-errors.

// Option A: wrapper (no extra dep)
const asyncHandler =
  (fn: RequestHandler): RequestHandler =>
  (req, res, next) =>
    Promise.resolve(fn(req, res, next)).catch(next);

// Option B: import once in app.ts (patches express globally)
import 'express-async-errors';

Error middleware — must have exactly four parameters:

app.use((err: unknown, req: Request, res: Response, _next: NextFunction) => {
  const status = err instanceof AppError ? err.status : 500;
  const message = err instanceof AppError ? err.message : 'Internal Server Error';
  res.status(status).json({ error: message });
});