Week 2: Express Fundamentals & Routing

1. Middleware & the Request/Response Cycle

An Express app is, at its core, a pipeline of functions that each get a chance to inspect or modify the incoming request before a response goes out. Every one of those functions — called middleware — receives the same three arguments: req (the incoming request), res (the outgoing response), and next (a function that hands control to the next middleware in line). If a middleware never calls next() and never sends a response, the request simply hangs forever — this is the single most common bug beginners hit with Express.

import express from "express";

const app = express();

// Built-in middleware: parses JSON request bodies into req.body
app.use(express.json());

// A simple custom middleware: logs every request as it arrives
app.use((req, res, next) => {
  console.log(`${req.method} ${req.path}`);
  next(); // without this, the request never reaches any route handler
});

app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Listening on http://localhost:${PORT}`);
});

Middleware runs in the order it's registered, top to bottom. That ordering is not cosmetic — it's the whole mechanism. express.json() has to run before any route handler that reads req.body, because it's the thing that actually parses the raw request stream into a usable object; register a route before it and req.body will be undefined in every handler that comes after. The same logic applies to authentication middleware in Week 6: it has to run before any route it's meant to protect, so it can reject the request early rather than letting a protected handler execute first.

// WRONG: route registered before the body parser
app.post("/echo", (req, res) => {
  res.json(req.body); // req.body is undefined here
});
app.use(express.json());

// RIGHT: parser first, then routes that depend on it
app.use(express.json());
app.post("/echo", (req, res) => {
  res.json(req.body); // works as expected
});

2. Modular Routing with express.Router()

Putting every route in main.ts works for a five-minute demo and falls apart fast in a real project. express.Router() creates a mini, self-contained Express app — it has its own .get(), .post(), and its own middleware chain — that you can build in its own file and mount onto the main app under a path prefix.

import { Router } from "express";

const usersRouter = Router();

// Because this router is mounted at /api/users in main.ts,
// this handles GET /api/users
usersRouter.get("/", (req, res) => {
  res.json({ users: [] });
});

// This handles GET /api/users/:id
usersRouter.get("/:id", (req, res) => {
  res.json({ id: req.params.id, name: "Ada Lovelace" });
});

// This handles POST /api/users
usersRouter.post("/", (req, res) => {
  const { name } = req.body as { name?: string };
  res.status(201).json({ id: "new-id", name });
});

export default usersRouter;

import express from "express";
import usersRouter from "./routes/users.js";
import postsRouter from "./routes/posts.js";

const app = express();
app.use(express.json());

app.use("/api/users", usersRouter);
app.use("/api/posts", postsRouter);

app.listen(3000);

The router itself never needs to know what prefix it's mounted under — it just handles paths relative to whatever app.use() mounts it on. That decoupling is what makes routers composable: the same usersRouter could be mounted at /api/users today and /v2/users tomorrow without touching a single line inside routes/users.ts. A typical project structure groups one router per resource, which is exactly the shape you'll extend with real persistence in Week 4 once each router talks to the database instead of returning hardcoded data.

3. Route Parameters, Query Strings & Basic Validation

Express exposes two different pieces of the URL on req: req.params for named segments in the route path itself (like :id), and req.query for everything after the ?. Both are always strings (or arrays/objects of strings for repeated or nested query keys) — Express never converts them to numbers or booleans for you, which is a common source of subtle bugs if you forget it.

import { Router } from "express";

const postsRouter = Router();

// GET /api/posts/42 -> req.params.id === "42" (a string, not a number)
postsRouter.get("/:id", (req, res) => {
  const id = Number(req.params.id);

  if (!Number.isInteger(id) || id <= 0) {
    return res.status(400).json({ error: "id must be a positive integer" });
  }

  res.json({ id, title: "Understanding Middleware" });
});

// GET /api/posts?page=2&limit=10
postsRouter.get("/", (req, res) => {
  const page = Number(req.query.page ?? 1);
  const limit = Number(req.query.limit ?? 20);

  if (!Number.isInteger(page) || page < 1) {
    return res.status(400).json({ error: "page must be a positive integer" });
  }
  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
    return res.status(400).json({ error: "limit must be between 1 and 100" });
  }

  res.json({ page, limit, posts: [] });
});

export default postsRouter;

This kind of hand-rolled validation is fine for a couple of fields, but it gets unwieldy fast once a request body has ten fields with different types, optional properties, and nested objects — that's exactly the problem Week 3 solves with Zod schemas that validate a whole request shape in one declarative pass instead of a wall of if statements. For now, the important habit is: never trust req.params or req.query to already be the type or shape you expect, because they always arrive as raw strings from the URL.

4. Centralized Error-Handling Middleware

Express recognizes an error-handling middleware by its arity — it must declare exactly four parameters, (err, req, res, next), in that order, even if you never use next. Register it last, after every other app.use() and route, and any error passed to next(err) anywhere in your app skips straight to it, instead of you needing a try/catch block around every single handler.

export class AppError extends Error {
  constructor(
    public statusCode: number,
    message: string,
  ) {
    super(message);
    this.name = "AppError";
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string) {
    super(404, `${resource} not found`);
  }
}

import type { ErrorRequestHandler } from "express";
import { AppError } from "../lib/errors.js";

export const errorHandler: ErrorRequestHandler = (err, req, res, next) => {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({ error: err.message });
  }

  // Anything that isn't one of our known errors is a bug --
  // log it fully but never leak internals to the client.
  console.error(err);
  res.status(500).json({ error: "Internal server error" });
};

import express from "express";
import usersRouter from "./routes/users.js";
import { errorHandler } from "./middleware/error-handler.js";
import { NotFoundError } from "./lib/errors.js";

const app = express();
app.use(express.json());
app.use("/api/users", usersRouter);

// 404 handler for unmatched routes -- runs if nothing above matched
app.use((req, res, next) => {
  next(new NotFoundError("Route"));
});

// Error handler MUST be registered last
app.use(errorHandler);

app.listen(3000);

Inside a synchronous handler, Express 4 automatically catches a thrown error and forwards it to your error middleware. Inside an async handler, it does not — a rejected promise from an awaited call that throws will crash the process unhandled unless you either wrap the call in try/catch and call next(err) yourself, or wrap the whole handler in a small helper that does it for you:

import type { Request, Response, NextFunction, RequestHandler } from "express";

export function asyncHandler(
  fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>,
): RequestHandler {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

// usage:
// usersRouter.get("/:id", asyncHandler(async (req, res) => {
//   const user = await findUser(req.params.id); // a throw here is caught and forwarded
//   res.json(user);
// }));

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.