Forem: Mohamed Idris

For ambitious devs who also feel tired

Mohamed Idris — Tue, 26 May 2026 00:11:04 +0000

Hey friends 👋

A lot of us struggle with the same thing. We want to keep learning. We sit down to code, then life happens, then a week goes by, then we feel bad about it.

I built a tiny Discord bot for a study server that fights this without adding more pressure.

What it does

You finish about 15 minutes of real coding. You click a button. You write one line about what you did. You post it. That's a "cup."

Your first cup of the day gives you XP. Extra cups still post in the feed, but no extra XP. The point is to show up, not to grind.

If you show up 5 days in a week, you get a small bonus and a public shoutout. If you miss days, nothing bad happens. Your XP stays. No streak to break.

You can also set a quest like NestJS or AWS exam with an optional target (e.g. 10 cups). When you hit the target, the bot celebrates it in the feed.

Why I built it this way

I read too much about gamification before writing a line of code. Three things came up over and over:

Leaderboards make people quit. When you can see who is ahead, study turns into competition. Some people grind. Most people compare and feel bad.
Daily streaks punish missing. One bad day breaks a 50-day streak. That feels worse than the win felt good.
Pre-set goals do not stick. Goals work when you choose them yourself.

So this server has:

No leaderboards.
No public daily streaks. Miss a day, you keep your XP.
Quests are optional. You set the name. You set the target. Or you set nothing.

Who it is for

Devs who want to keep learning but feel the cold-start every time. Especially helpful if you are a student or in your first few years of work. The default focus is TypeScript fullstack (NestJS, React, Prisma) but you can tag your cups with anything you are learning.

Want to join?

Check first comment or drop a comment or DM me in case the invitation link got expired. The server is small on purpose.

It is free. There is no course. There is no cohort. Just a place to show up.

Show up, log it, keep moving. ☕

Learning NestJS As If You Built It Yourself

Mohamed Idris — Sun, 24 May 2026 13:12:00 +0000

If you have ever built a Node.js app with plain Express, you know the moment. The first three routes feel great. By route thirty, you have a routes/ folder, a middlewares/ folder, a utils/ folder, and one giant app.js where everyone wires things up however they feel like that day. There is no rulebook, so every developer invents one.

That is fine for a weekend project. For a real backend with a team, it gets painful. You want structure that you do not have to invent, you want testability without bending over backwards, and you want your code to look the same whether it was written today or a year ago.

That is the gap NestJS fills.

What is NestJS, really

Think of NestJS as Express (or Fastify, your pick) with a wise older sibling sitting next to it. The sibling says "actually, put your HTTP code over here, your business logic over there, your validation right at the door, and ask me when you need something instead of building it yourself".

It is opinionated on purpose. Once you learn the pattern once, every NestJS app on the planet starts to feel familiar.

The sibling speaks fluent TypeScript and loves decorators. That is the whole vibe.

Let's pretend we are building one

We want a Node.js framework that scales nicely with the team and the codebase. We will call it NestJS. As we design it, every decision we make is a thing you will see again and again in real code, so let's make them on purpose.

For our running example, imagine a tiny app: a little online library. Books and members. Nothing fancy.

Decision 1: Code should be organized in feature boxes

We will call these boxes modules. A module is a folder with everything one feature needs: its routes, its logic, its data shapes, its tests. If you delete the folder, the feature is gone, and nothing else breaks.

A module is just a class with a decorator on top:

// books/books.module.ts
import { Module } from "@nestjs/common";
import { BooksController } from "./books.controller";
import { BooksService } from "./books.service";

@Module({
  controllers: [BooksController],
  providers:   [BooksService],
  exports:     [BooksService],
})
export class BooksModule {}

Read that decorator like a mini contract:

controllers are the doors of this feature, the things that listen for HTTP requests.
providers are the workers that do the actual job (services, repositories, helpers).
exports is what this module is willing to share with other modules. If you do not export it, it stays private.

Then a top level AppModule wires the features together:

@Module({
  imports: [BooksModule, MembersModule],
})
export class AppModule {}

Modules give us boundaries. Boundaries give us sanity.

Tiny tip: keep one feature per folder, not one technical layer per folder. A books/ folder with controller, service, dto, and entity inside beats four parallel folders called controllers/, services/, dtos/, entities/. Modern NestJS guides all push this style.

Decision 2: HTTP stuff lives in a controller

We need something that receives requests and returns responses. We do not want HTTP code mixed into business logic, so we put it in its own class called a controller. Decorators do the routing for us.

// books/books.controller.ts
import { Controller, Get, Post, Body, Param } from "@nestjs/common";
import { BooksService } from "./books.service";
import { CreateBookDto } from "./dto/create-book.dto";

@Controller("books")
export class BooksController {
  constructor(private readonly books: BooksService) {}

  @Get()
  findAll() {
    return this.books.findAll();
  }

  @Get(":id")
  findOne(@Param("id") id: string) {
    return this.books.findOne(id);
  }

  @Post()
  create(@Body() dto: CreateBookDto) {
    return this.books.create(dto);
  }
}

A few things worth noticing, because these patterns repeat everywhere:

@Controller("books") mounts every route in the class under /books.
@Get, @Post, @Put, @Patch, @Delete map to HTTP verbs. The argument inside is the sub path.
@Param, @Body, @Query, @Headers pull pieces out of the request for you. No more req.body.something, you ask for what you want directly.
The controller does not know what a database is, and that is the point. It just calls the service.

The controller is the door. It greets visitors and points them inside.

Decision 3: The brain lives in a service

Real work belongs in a class with no HTTP awareness, so the same logic can be reused from a CLI, a queue worker, a GraphQL resolver, or a test. We call these classes services, and we mark them with @Injectable() so our framework knows it is allowed to manage them.

// books/books.service.ts
import { Injectable, NotFoundException } from "@nestjs/common";

@Injectable()
export class BooksService {
  private books = [
    { id: "1", title: "The Little Prince", author: "Saint-Exupery" },
  ];

  findAll() {
    return this.books;
  }

  findOne(id: string) {
    const book = this.books.find((b) => b.id === id);
    if (!book) throw new NotFoundException(`Book ${id} not found`);
    return book;
  }

  create(dto: { title: string; author: string }) {
    const book = { id: String(this.books.length + 1), ...dto };
    this.books.push(book);
    return book;
  }
}

Services are where the boring, valuable code lives. They are also the easiest things in the universe to unit test, because they are just classes with constructor arguments.

Decision 4: Don't `new` your stuff, ask for it

This is the heart of NestJS, and it is the part that feels weird for about two days, then makes total sense.

Look at the controller again:

constructor(private readonly books: BooksService) {}

We never wrote new BooksService() anywhere. We just declared "I need a BooksService", and somehow we got one. That is dependency injection, and the framework's IoC container is the thing pulling the strings.

Here is roughly what happens at boot:

NestJS reads every module's providers array.
For each provider, it figures out what it needs (by looking at constructor types).
It builds them in the right order, hands each one its dependencies, and caches the result.
By default, every provider is a singleton, one shared instance for the whole app.
When a controller is created, the container wires in the services it asked for.

Why bother? Three reasons that pay off forever:

Testing is trivial. In a test you can hand a controller a fake service. No mocking libraries required.
Swapping implementations is one line. Change which class is bound to a token in the module, and the entire app uses the new one.
No spaghetti require graph. Modules tell the framework what they expose, and that is the only path other modules can use.

You can also bind by token instead of by class, for things like config or external clients:

@Module({
  providers: [
    {
      provide: "BOOKS_REPO",
      useFactory: (config: ConfigService) =>
        new BooksRepo(config.get("DB_URL")),
      inject: [ConfigService],
    },
  ],
})
export class BooksModule {}

Then inside a service:

constructor(@Inject("BOOKS_REPO") private repo: BooksRepo) {}

That same trick is how you swap a real database for an in memory fake in tests.

Decision 5: Validate at the door with DTOs

We agreed earlier that controllers are the door of the app. Doors should check who is coming in. So we want to define exactly what the body of POST /books looks like, and reject anything weird before it ever reaches the service.

We use a plain class called a DTO (Data Transfer Object), and we decorate its fields with rules from class-validator:

// books/dto/create-book.dto.ts
import { IsString, Length, IsOptional, IsInt, Min } from "class-validator";

export class CreateBookDto {
  @IsString()
  @Length(1, 120)
  title!: string;

  @IsString()
  @Length(1, 80)
  author!: string;

  @IsOptional()
  @IsInt()
  @Min(0)
  pages?: number;
}

Then in main.ts, we turn on the global ValidationPipe once, and the whole app is protected:

// main.ts
import { ValidationPipe } from "@nestjs/common";
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,            // drop fields we did not declare
      forbidNonWhitelisted: true, // or throw if someone tries
      transform: true,            // turn the body into a real DTO instance
      transformOptions: { enableImplicitConversion: true },
    }),
  );

  await app.listen(3000);
}
bootstrap();

That single block of options is one of the highest leverage settings in NestJS. whitelist strips junk, forbidNonWhitelisted shouts about junk, transform gives you a typed DTO instance instead of a plain object. Most security and bug pain disappears once this is on.

For partial updates, you do not rewrite the whole DTO. NestJS gives you helpers:

import { PartialType } from "@nestjs/mapped-types";
import { CreateBookDto } from "./create-book.dto";

export class UpdateBookDto extends PartialType(CreateBookDto) {}

Now every field is optional, but every existing rule still applies.

Decision 6: Plug in extra logic with a tiny pipeline

Real apps need cross cutting things. Logging. Auth. Caching. Error handling. We do not want any of that mess inside controllers or services, so we offered five clean places to plug in. The order they run in is fixed and worth memorizing:

incoming request
    -> Middleware
        -> Guards
            -> Interceptors (before)
                -> Pipes
                    -> Controller handler
                        -> Service
                    -> Interceptors (after / response shaping)
                -> Exception Filters (only if something throws)
outgoing response

Each one has a job:

Middleware is the classic Express style function. Runs first, knows nothing about which route, good for logging, request ids, raw header tweaks.
Guards answer one question: "is this request allowed in?". Auth, roles, feature flags. They have access to the route metadata, so they know which controller and handler they are guarding.
Interceptors wrap the handler. They can run code before and after, modify the response, add caching, add timing logs. Powered by RxJS observables.
Pipes transform and validate inputs. ValidationPipe is one. ParseIntPipe, ParseUUIDPipe, ParseDatePipe (added in NestJS 11) are others.
Exception Filters catch errors and shape them into nice HTTP responses. You can have a global one for consistent error JSON.

A guard looks like this:

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(ctx: ExecutionContext): boolean {
    const req = ctx.switchToHttp().getRequest();
    return Boolean(req.headers.authorization);
  }
}

Apply it to one route, one controller, or globally. Same shape for the rest of the family.

If you only remember one rule: middleware does not know the route, guards do. That distinction will save you future headaches.

Decision 7: Make it fast and easy to start

NestJS 11 (the current major version) made some quality of life moves we should mention, because you will see them in fresh projects:

SWC is the default compiler. Cold starts and rebuilds are dramatically faster than the old tsc based dev loop. You barely notice the build step anymore.
Vitest is the suggested test runner in new project templates, and it pairs nicely with SWC.
Standalone applications via NestFactory.createApplicationContext(AppModule) give you the IoC container without an HTTP server, perfect for CLI tools, cron jobs, and serverless handlers that just want dependency injection.
ConsoleLogger supports JSON output out of the box, so shipping logs to your aggregator does not need a custom logger anymore.
IntrinsicException lets you throw errors that skip the framework's automatic logging, useful for sensitive flows.
ParseDatePipe validates and converts incoming date strings into real Date objects.
Better CSRF helpers and small but nice microservice transport improvements (unwrap() to reach the underlying client).

You do not need to use any of this on day one. But knowing these exist means you will recognize them when you see them in code or release notes.

A peek under the hood

What really happens when a request hits a NestJS app, end to end:

Node receives the request through the underlying platform (Express by default, Fastify if you swapped it in).
NestJS runs registered middleware in order.
Guards run for the matched route. If any returns false or throws, we stop.
Interceptors (before phase) wrap the handler call.
Pipes transform and validate each parameter (so your @Body() dto becomes a real CreateBookDto with validations applied).
The controller method runs. It calls a service, which the IoC container had already wired up.
The return value flows back through the interceptor (after phase), which can map, cache, or log it.
If anything threw on the way, exception filters catch it and turn it into a clean HTTP response.
Node writes the response back to the client.

That entire flow is what makes NestJS feel "boring in a good way". You always know where to put new code.

Tiny tips that will save you later

One feature, one folder, one module. Do not pre split by layer.
Turn on the global ValidationPipe in main.ts on day one, with whitelist, forbidNonWhitelisted, and transform enabled.
Use @nestjs/config with a Zod or Joi schema so missing env vars fail at boot, not at 3am in production.
Keep controllers thin. If a controller method is more than a few lines, push the logic into the service.
Inject by class when you can, by token when you must. Tokens are great for swapping implementations and for things you cannot easily type as a class.
Default scope is singleton. Only opt into request scope when you genuinely need per request state, since it is more expensive.
Use nest g generators (nest g module books, nest g resource books) early on. They scaffold the boilerplate you would have typed anyway, in the canonical shape.
Test services as plain classes. Test controllers with a fake service. Reach for Test.createTestingModule only when you actually need the DI graph.

Wrapping up

So that is the whole story. We wanted Express scale to stop being painful. We built a framework that gives every app the same shape:

Module
  -> Controller (the door, decorated routes)
    -> Service (the brain, plain TypeScript)
      -> whatever it needs (repos, clients, configs)

Then we surrounded that core with a tidy pipeline: middleware, guards, interceptors, pipes, filters, each with one job. We let the IoC container wire everything together, so you never type new and never wonder where a dependency came from. We made validation a one liner at the boundary. And in version 11, we made the whole thing faster to start and lighter to ship.

Once that shape clicks, NestJS stops feeling like a framework you are learning, and starts feeling like a project layout you can fall back on, no matter how big the codebase grows.

Happy building, and put a nice book on the shelf for me.

Learning Express.js As If You Built It Yourself

Mohamed Idris — Sat, 23 May 2026 13:11:00 +0000

If you have ever opened the raw node:http module and tried to write a real server with it, you remember the moment. You wrote http.createServer((req, res) => { ... }). Then you tried to read JSON from the body and discovered there is no req.body. You parsed it with streams. Then you tried to route a POST /users differently from GET /users and ended up with a giant if/else ladder. Then you added auth, logging, error handling, CORS, and the file became unreadable.

Node gave you a great low level engine, but a real web server needs a friendly chassis on top. Express is that chassis.

That is the gap Express fills.

What is Express, really

Think of Express as a small assembly line for HTTP requests. A request walks in one end. It passes through a series of stations, where each station does one thing: parse the body, check the cookie, log the URL, look up the user, validate the input. At the end, a route handler builds a response. The response walks back out the door.

Each station is a middleware. The whole assembly line is the app. You decide which stations to install, in what order. That single idea, plus a list of HTTP verb shortcuts, is essentially the entire framework.

Two ideas drive everything:

Middleware chain. Every request passes through a sequence of functions. Each one calls next() to pass control along, or sends a response to stop.
Unopinionated. Express does not tell you how to structure your app. It gives you a tiny, sharp tool and gets out of your way. That is its strength and its trap.

That is the whole vibe.

Let's pretend we are building one

We want a friendly Node.js framework that handles routing, body parsing, and middleware composition without inventing a new language. We will call it Express.js.

For the running example, we are building a tiny Stickies API: tiny sticky notes, owned by users, taggable, searchable. Small, but it lets us touch every important corner.

Decision 1: Hello world in five lines

import express from "express";

const app = express();

app.get("/", (req, res) => {
  res.send("Hello, sticky notes.");
});

app.listen(3000, () => console.log("listening on :3000"));

That is a working web server. Read it like a sentence: when a GET request comes in for /, send back a string. Listen on port 3000.

The two things every senior should know about that snippet:

app.get("/", handler) is sugar for "add a middleware that only runs for GET /".
res.send() auto sets Content-Type based on the value (string, Buffer, JSON, etc). Use res.json(obj) when you want to be explicit and force application/json.

Decision 2: Routes, the verbs and the paths

Every HTTP verb has a method on the app:

app.get   ("/stickies",          listStickies);
app.post  ("/stickies",          createSticky);
app.get   ("/stickies/:id",      readSticky);
app.patch ("/stickies/:id",      updateSticky);
app.delete("/stickies/:id",      deleteSticky);
app.all   ("/stickies/:id/lock", lockHandler); // any verb

The colon prefix marks a route parameter. Inside the handler, you read it from req.params:

function readSticky(req, res) {
  const { id } = req.params;          // string
  const note = db.getSticky(id);
  if (!note) return res.status(404).json({ error: "not found" });
  res.json(note);
}

Three sources of input every Express handler reads from:

req.params   // path params: /stickies/:id  -> { id: "42" }
req.query    // query string: ?tag=urgent   -> { tag: "urgent" }
req.body     // request body (after a parser middleware sets it)

Plus the headers and cookies:

req.headers["authorization"];
req.cookies?.session;       // requires cookie-parser middleware

Modern advice: types for req.body, req.params, and req.query should come from a Zod schema validated at the start of the handler, not from hand annotated TypeScript generics. We will see this in a moment.

Decision 3: Middleware, the soul of Express

A middleware is a function with the shape (req, res, next) => void. It can:

Read or modify the request.
Write a response and end the chain.
Call next() to pass to the next middleware.
Call next(err) to skip ahead to error middleware.

function logger(req, res, next) {
  const start = Date.now();
  res.on("finish", () => {
    console.log(`${req.method} ${req.url} ${res.statusCode} ${Date.now() - start}ms`);
  });
  next();
}

app.use(logger);

app.use(...) mounts a middleware that runs on every request. You can also mount per path:

app.use("/api", apiAuth);  // only for /api/*

Order matters. A request flows top to bottom through the middleware list, and the first one to write a response wins. This is why the order of app.use calls is your program's pipeline.

A typical production app stacks them like this:

import express from "express";
import helmet  from "helmet";
import cors    from "cors";
import compression from "compression";
import morgan  from "morgan";

const app = express();

app.use(helmet());                              // security headers
app.use(cors({ origin: process.env.WEB_ORIGIN, credentials: true }));
app.use(compression());                         // gzip / brotli
app.use(morgan("tiny"));                        // request logging
app.use(express.json({ limit: "1mb" }));        // parse JSON bodies
app.use(express.urlencoded({ extended: true })); // parse form bodies

// your routes
app.use("/api/stickies", stickiesRouter);

// error middleware (last)
app.use(errorHandler);

That stack is essentially the same in every Express app on the planet. Memorize the shape.

Decision 4: Built in body parsers (no more body-parser)

Once upon a time you installed body-parser. Now Express ships JSON and URL-encoded parsers built in:

app.use(express.json({ limit: "1mb" }));
app.use(express.urlencoded({ extended: true }));
app.use(express.text());        // text bodies
app.use(express.raw());         // Buffer bodies

Always set a limit. The default is 100KB and that is fine for most endpoints, but explicit beats default. An unbounded JSON parser is a denial of service waiting to happen.

For file uploads, reach for Multer (multipart/form-data) or stream the body yourself if it is a single file. Never read uploads into memory for big files.

Decision 5: Routers for modular structure

A Router is a mini app. Same .get, .post, .use API. You compose them with app.use(prefix, router).

// routes/stickies.ts
import { Router } from "express";

const r = Router();

r.get("/",     listStickies);
r.post("/",    createSticky);
r.get("/:id",  readSticky);
r.patch("/:id", updateSticky);

export default r;

// app.ts
import stickies from "./routes/stickies";
app.use("/api/stickies", stickies);

Senior level habits:

One router per resource. A stickies.ts router, a users.ts router, a tags.ts router.
Mount under a versioned prefix. app.use("/api/v1", apiV1) so future you can add v2 without a rewrite.
Group middleware on the router, not on every route. r.use(authRequired) at the top of an admin router runs once per request.

A full senior style folder layout for a non-trivial app:

src/
  app.ts                  -> app composition
  server.ts               -> listen + graceful shutdown
  routes/
    stickies.ts
    users.ts
  controllers/
    stickies.controller.ts
  services/
    stickies.service.ts
  middleware/
    auth.ts
    error.ts
    rate-limit.ts
  schemas/
    sticky.schema.ts        -> Zod schemas
  lib/
    db.ts
    logger.ts

Express will not enforce this. It is convention. Pick one and stick with it.

Decision 6: Async handlers (the Express 5 superpower)

In Express 4, an async route that threw or rejected would crash the process unless you wrapped it in asyncHandler or installed express-async-errors. It was the single most common bug in the Express world.

Express 5 (released in October 2024) fixes this. Async route handlers and middleware that return a rejected Promise now automatically forward to the error middleware. You no longer need a wrapper.

// works correctly in Express 5
r.get("/:id", async (req, res) => {
  const sticky = await db.stickies.findUnique({ where: { id: req.params.id } });
  if (!sticky) throw new NotFoundError("sticky not found");
  res.json(sticky);
});

If a senior interview asks you "how do you handle async errors in Express", the modern answer in 2026 is "I use Express 5 and I just throw or reject. The framework forwards to my error middleware."

If you are stuck on Express 4, the patterns:

// option 1: a wrapper
const wrap = (fn) => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
r.get("/:id", wrap(async (req, res) => { /* ... */ }));

// option 2: a single import
import "express-async-errors"; // monkey patches Express to handle async

But upgrade. Express 5 is stable and the migration is small.

Decision 7: Error handling middleware, the four argument signature

An error handler is a middleware with four arguments instead of three. Express uses the arity to find them:

function errorHandler(err, req, res, next) {
  // ...
}

Mount it last. Anything that calls next(err) (or throws inside an async handler in Express 5) lands here.

A real error middleware that maps known errors to statuses, logs unknown ones, and never leaks internals:

import { ZodError } from "zod";

class HttpError extends Error {
  constructor(public status: number, message: string, public code?: string) {
    super(message);
  }
}

function errorHandler(err, req, res, next) {
  if (err instanceof ZodError) {
    return res.status(422).json({
      error: "Invalid input",
      issues: err.issues,
    });
  }

  if (err instanceof HttpError) {
    return res.status(err.status).json({ error: err.message, code: err.code });
  }

  req.log?.error({ err }, "Unhandled error");
  res.status(500).json({ error: "Internal server error" });
}

Senior level rule: the error middleware is the only place that decides the status and the body of an error response. Handlers throw, middleware translates. The system stays consistent.

Decision 8: Validate every input with Zod

Express does not validate anything for you. Use a Zod schema at the top of every handler, and you get safety, types, and a clear failure mode for free.

import { z } from "zod";

const CreateSticky = z.object({
  body:  z.string().min(1).max(500),
  tags:  z.array(z.string()).default([]),
  color: z.enum(["yellow", "pink", "blue"]).default("yellow"),
});

r.post("/", async (req, res) => {
  const data = CreateSticky.parse(req.body);   // throws ZodError on failure
  const sticky = await db.stickies.create({ data });
  res.status(201).json(sticky);
});

When parse throws, your error middleware turns it into a 422 with the issues. Hands free.

If you want a one liner middleware version:

const validate = (schemas: { body?: ZodSchema; query?: ZodSchema; params?: ZodSchema }) =>
  (req, res, next) => {
    if (schemas.body)   req.body   = schemas.body.parse(req.body);
    if (schemas.query)  req.query  = schemas.query.parse(req.query);
    if (schemas.params) req.params = schemas.params.parse(req.params);
    next();
  };

r.post("/", validate({ body: CreateSticky }), createSticky);

Decision 9: Auth, the modern Node story

Express has zero auth out of the box, on purpose. Three patterns you will see:

Session cookies with a store like connect-redis. Use express-session plus cookie-parser. The classic, still excellent for first party web apps.
JWT in HttpOnly cookies, verified with a tiny middleware that reads the cookie, verifies the signature, and attaches req.user.
Auth.js / Lucia / hosted services (Clerk, Kinde, WorkOS) when you want to stop thinking about auth.

A minimal cookie session example:

import session from "express-session";
import RedisStore from "connect-redis";

app.use(session({
  store: new RedisStore({ client: redis }),
  secret: process.env.SESSION_SECRET!,
  cookie: {
    httpOnly: true,
    secure:   true,
    sameSite: "lax",
    maxAge:   1000 * 60 * 60 * 24 * 7,
  },
  resave: false,
  saveUninitialized: false,
}));

function authRequired(req, res, next) {
  if (!req.session.userId) return res.status(401).json({ error: "unauthorized" });
  next();
}

app.use("/api/admin", authRequired);

Senior level rule: never trust the client about auth. The session check happens server side, on every protected request, in middleware.

Decision 10: Security middleware that should be on by default

A short checklist most teams skip and regret later:

import helmet      from "helmet";
import cors        from "cors";
import rateLimit   from "express-rate-limit";
import hpp         from "hpp";

app.disable("x-powered-by");                     // do not advertise the framework
app.set("trust proxy", 1);                       // honor X-Forwarded-* behind a proxy

app.use(helmet());                               // sets a dozen security headers
app.use(cors({ origin: process.env.WEB_ORIGIN, credentials: true }));
app.use(hpp());                                  // protects against parameter pollution

app.use("/api/", rateLimit({
  windowMs: 60_000,
  limit:    120,
  standardHeaders: "draft-7",
  legacyHeaders: false,
}));

The senior level extras:

Set a body size limit on express.json({ limit }).
Set timeouts on the server: server.headersTimeout = 60_000; server.requestTimeout = 30_000;.
Validate every input. No exceptions.
Use parameterized DB queries. No string concatenation.

Decision 11: TypeScript with Express, the friendly way

You can type Express by hand, or you can let inference do most of the work via Zod and a tiny helper:

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

// hand typed handler
const createSticky: RequestHandler<{}, Sticky, CreateStickyDto> =
  async (req, res) => {
    const sticky = await service.create(req.body);
    res.status(201).json(sticky);
  };

The cleaner pattern in 2026: stop typing req.body by hand, let Zod validate and infer:

const CreateSticky = z.object({ body: z.string(), tags: z.array(z.string()) });
type CreateStickyInput = z.infer<typeof CreateSticky>;

r.post("/", async (req, res) => {
  const data: CreateStickyInput = CreateSticky.parse(req.body);
  // ...
});

For shared client / server typed contracts, look at ts-rest or tRPC. They put the schema in one place, both sides import it, no drift.

Decision 12: Testing Express handlers

Two patterns:

Supertest, the classic

Drives your Express app in memory, no real server needed. Works with Vitest or Jest.

import request from "supertest";
import { app } from "../src/app";

it("creates a sticky", async () => {
  const res = await request(app)
    .post("/api/stickies")
    .send({ body: "Buy milk" })
    .expect(201);

  expect(res.body.body).toBe("Buy milk");
});

Real HTTP for integration tests

When you want the full stack (rate limit, auth, real database), run the app on an ephemeral port and hit it with fetch. Slower, more realistic. Pair with a transactional rollback per test or a Postgres / Mongo Memory Server.

The boundary that gives the best return: one Supertest test per route. Hit the happy path, hit the validation error, hit the auth error. That covers most regressions in five minutes.

Decision 13: Graceful shutdown and observability

Senior level details that beginners skip:

const server = app.listen(3000);

function shutdown(signal: string) {
  console.log(`received ${signal}, shutting down`);
  server.close(() => {
    db.disconnect().finally(() => process.exit(0));
  });
  setTimeout(() => process.exit(1), 10_000).unref();
}

process.on("SIGINT",  () => shutdown("SIGINT"));
process.on("SIGTERM", () => shutdown("SIGTERM"));

A long running process should drain in flight requests on SIGTERM, close the database, and only then exit. Without this, deploys interrupt users mid request.

For logs and metrics: pick pino (fast structured logger) and OpenTelemetry (tracing and metrics). Drop a request id middleware so every log line is correlatable.

Decision 14: When to pick Express, when to pick something else

Senior engineers know when to reach for a different tool. The 2026 landscape:

Express: the default for "I want a small server, I want to control everything". Tons of middleware, tons of tutorials, runs everywhere Node runs. Slower than the new generation, but only by milliseconds. For 99% of apps the difference does not matter.
Fastify: a faster, more opinionated cousin of Express. Native schema validation (via Ajv), plugin system, very good performance. Pick this when throughput matters or you want stricter conventions.
Hono: tiny, ultra fast, built for the edge (Cloudflare Workers, Bun, Deno, AWS Lambda). Same vibe as Express, modern API. Pick this when you target serverless or the edge.
NestJS: a full framework on top of Express (or Fastify). Modules, controllers, dependency injection, opinionated patterns. Pick this when the team is large and you want structure for free. (See the NestJS post.)
tRPC: not a server framework, a typed RPC layer. Sits inside an Express or Fastify app and gives you end to end type safety with no codegen. Pick this when client and server are both TypeScript and you control both.

If you do not know what to pick, pick Express. It is the lingua franca. You can always migrate later.

A peek under the hood

What really happens when a request hits an Express app:

Node's http server emits a "request" event with the raw req and res.
Express's app function receives them. It walks its internal router stack (the middleware list).
For each middleware, Express checks the path and method. If they match, the function runs.
next() advances. next(err) skips to the next four argument middleware. A response (res.send, res.json, res.end) ends the chain.
Once the response is committed, Node sends it back to the client and the request lifecycle ends.

That whole loop is built on top of the http module. No magic, no proxy, no codegen. Express is, deep down, a very polished for loop over middleware functions. That clarity is its greatest gift.

Tiny tips that will save you later

Upgrade to Express 5. Free async error handling, free upgrades.
Mount middleware in the right order. Helmet first, body parsers next, routes after, error handler last.
Set app.disable("x-powered-by").
Always validate input with Zod. Trust nothing.
Limit body size.
One router per resource. One file per router.
Throw real Error objects with cause.
Never console.log in production code. Use pino or the framework logger of your choice, with structured fields.
Add a /health endpoint. Your load balancer wants it.
Graceful shutdown on SIGTERM.
Use Supertest for handler tests. Fast feedback, real HTTP semantics.
Generate API docs from Zod schemas with zod-to-openapi. Free OpenAPI spec, no extra source of truth.

Wrapping up

So that is the whole story. We were tired of fighting raw node:http. We built a tiny chassis that turns the request lifecycle into an assembly line of middleware. Each station does one thing. The first one to write a response stops the line. Routes are middleware that match a verb and a path. Errors are middleware with four arguments. Async errors, in Express 5, just work.

We learned to mount security middleware first, validate every input with Zod, push business logic into services, return errors through a single error handler, and shut down gracefully when the platform asks. We picked routers as our unit of structure. We tested with Supertest. We compared Express to Fastify, Hono, NestJS, and tRPC, and learned when each one wins.

Once that map is in your head, Express stops feeling like "the old way to write a Node server" and starts feeling like the calm, reliable backbone it has been for a decade. It is small enough to learn in an afternoon and deep enough to build a career on.

Happy serving, and may your next() always lead somewhere useful.

Learning Prisma As If You Built It Yourself

Mohamed Idris — Fri, 22 May 2026 13:10:00 +0000

If you have ever written raw SQL inside a real app, you already know the feeling. At first it looks fine, then a few weeks later you are staring at a 40 line query, scared to touch it because changing one comma might bring down half the website. Maintaining raw SQL across a growing app is just hard. The shape of the data changes, the team grows, the queries multiply, and suddenly you spend more time fixing strings than writing features.

That is exactly the gap an ORM fills.

What is an ORM, really

Think of an ORM as a friendly translator. You speak your favorite programming language, and the translator turns it into SQL on the fly. You say "give me all users with their pets", and the translator quietly walks over to the database, writes the proper SQL, brings back the rows, and hands you back nice objects you can actually work with.

No more building strings by hand. No more guessing if you forgot a JOIN. The translator knows the database, you stay in your language.

Let's pretend we are building one

We love JavaScript and TypeScript. So let's say we want to build our own ORM for the JS world. We will call it Prisma.

Before we write a single query, we need a few decisions. These decisions are basically the design of the whole library, and once you see them, every Prisma snippet on the internet starts to feel obvious.

Decision 1: We need a map of the database

The translator can only translate if it knows the language. So our ORM needs to know what tables exist, what columns they have, what types those columns are, and how tables relate to each other.

We could read this from the database every time, but that is slow and fragile. So instead we ask the developer to write it down once, in a file we will call schema.prisma. This becomes the single source of truth.

Here is what a tiny pet adoption app might look like:

// schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id    Int     @id @default(autoincrement())
  name  String
  email String  @unique
  pets  Pet[]
}

model Pet {
  id        Int       @id @default(autoincrement())
  name      String
  species   String
  adoptedAt DateTime?
  owner     User?     @relation(fields: [ownerId], references: [id])
  ownerId   Int?
}

Three blocks, each with a clear job:

generator tells Prisma what kind of client to build for us. We picked the JS one.
datasource tells Prisma which database we are talking to and where it lives.
model blocks describe our tables. Each line is a column, with a type and optional attributes.

A few cute things to notice:

@id says this is the primary key.
@default(autoincrement()) means the database fills it in for us.
@unique adds a uniqueness constraint, like for emails.
pets Pet[] says a user has many pets. The [] after Pet is what tells you it is a list, not just one.
The ? after a type (like User? and Int?) means "this is optional, it can be empty". Without ?, the field is required.
The matching owner and ownerId on Pet is how we say "each pet belongs to one user". @relation wires the foreign key.

About that ?: this is a pet adoption app, so a pet can sit in the shelter for a while with no owner yet. Making owner and ownerId optional says "a pet may or may not have a human". Same idea for adoptedAt: no adoption date until they are actually adopted. If we wanted to force every pet to have an owner from day one, we would drop the ? and the database would refuse to create a pet without one.

That is the whole schema. No SQL yet.

Decision 2: Turn the schema into actual code

Now the magic step. We run:

npx prisma migrate dev --name init

This does two things at once. It creates the SQL tables in the database to match our schema, and it generates a Prisma Client tailored to those exact models. The client is regular JS/TS code that lives in node_modules/@prisma/client (or a custom folder you point to). Every time the schema changes, you regenerate, and the client updates with it.

This is the part people miss when they first see Prisma. The client is not a generic library. It is custom built for your schema. That is why autocomplete knows your fields, your relations, and your types. Nothing is guessed.

Decision 3: Every call starts with `prisma`

We agreed early on that every query in our ORM should start with the same word, so the API feels predictable. We went with prisma, which is the instance of the generated client.

import { PrismaClient } from "@prisma/client";

const prisma = new PrismaClient();

What is prisma here? It is the client object we just generated. Under the hood, when you call something on it, the client builds a structured query, hands it to a query engine (a small native binary that ships with Prisma), and the engine talks to the actual database, gets the rows, and returns them as plain JS objects with full types attached. You never see the SQL unless you ask for it.

So when you read prisma.something.somethingElse(...), you can read it like a sentence:

Hey Prisma client, on the User table, please find many rows that match this.

Let's see it.

Decision 4: After `prisma.`, you name the table

We called these "models" in the schema, and they map one to one with the lowercase property on the client. So model User becomes prisma.user, model Pet becomes prisma.pet. Simple rule.

prisma.user;  // the users table
prisma.pet;   // the pets table

Nothing happens yet. We are just pointing at a table. The action comes next.

Decision 5: After the model, you pick a command

Each model has the same set of commands, because every table can be read, written to, updated, and deleted. The names are boring on purpose, which is good, because boring is easy to remember.

prisma.user.findMany();    // get a list
prisma.user.findUnique();  // get one by a unique field
prisma.user.findFirst();   // get the first that matches
prisma.user.create();      // insert a row
prisma.user.update();      // change a row
prisma.user.delete();      // delete a row
prisma.user.upsert();      // update if it exists, otherwise create
prisma.user.count();       // how many match

That is basically the whole vocabulary. Once you learn it for user, you know it for every other model in your schema.

Decision 6: Inside the command, you describe what you want

Most commands take a single object as the argument, and the keys of that object are little instructions. Think of it as filling out a form.

The most useful keys are:

where to filter
data to write
select to pick which fields come back
include to pull related rows
orderBy, take, skip for sorting and paginating

Let's adopt some pets.

Creating a user

const mia = await prisma.user.create({
  data: {
    name: "Mia",
    email: "mia@cats.dev",
  },
});

data is what we are putting into the row. Notice how we did not pass id or pets. The id is auto, and pets is a relation we have not used yet.

Finding a user

const someone = await prisma.user.findUnique({
  where: { email: "mia@cats.dev" },
});

where only accepts unique fields here, because findUnique is supposed to return at most one. If you want to filter on anything, use findMany or findFirst.

const miaLikes = await prisma.user.findMany({
  where: {
    name: { contains: "Mia" },
  },
});

That contains is one of many handy filters Prisma gives you. There is equals, not, in, startsWith, endsWith, gt, lt, and so on. Same idea: it is just a key in the form.

Updating

await prisma.user.update({
  where: { id: mia.id },
  data:  { name: "Mia Rose" },
});

Two keys here. where says which row, data says what to change. Reads like English.

Deleting

await prisma.user.delete({
  where: { id: mia.id },
});

Same shape. Just where.

Decision 7: Joining tables with `include`

Now to the fun part. We promised a translator that handles relations for us. So when we want a user with their pets, we should not have to write a JOIN by hand.

We added a key called include. You hand it the names of the relations you want pulled in, and it returns nested data:

const usersWithPets = await prisma.user.findMany({
  include: {
    pets: true,
  },
});

The result looks like this, naturally nested:

[
  {
    id: 1,
    name: "Mia Rose",
    email: "mia@cats.dev",
    pets: [
      { id: 1, name: "Whiskers", species: "cat", ownerId: 1, adoptedAt: ... },
      { id: 2, name: "Mochi",    species: "cat", ownerId: 1, adoptedAt: ... },
    ],
  },
  ...
]

Under the hood, Prisma does the right thing for you. It might use a JOIN, it might use two queries and stitch them together, depending on the relation and the database. You do not have to care.

You can go deeper too. Let's get every user, with their pets, and only the pet's name:

const cuteList = await prisma.user.findMany({
  include: {
    pets: {
      select: { name: true },
    },
  },
});

select is the cousin of include. While include says "give me the related rows on top of everything else", select says "give me ONLY these fields". You can mix them, and Prisma's types follow along, so the returned object literally has only the fields you picked. No more guessing what the API returned.

You can even create related rows together, in one call:

await prisma.user.create({
  data: {
    name: "Sam",
    email: "sam@dogs.dev",
    pets: {
      create: [
        { name: "Biscuit", species: "dog" },
        { name: "Pepper",  species: "cat" },
      ],
    },
  },
});

One round trip, two tables, zero SQL written by you. That moment is when most people fall in love with Prisma.

Decision 8: Migrations are part of the story

Schemas change. We add a column, we rename a field, we add a new model. Our ORM should make that safe.

# After changing schema.prisma
npx prisma migrate dev --name added_age_to_pet

This generates a SQL migration file, applies it to your dev database, and regenerates the client so your code knows about the new field. In production you usually run prisma migrate deploy, which only applies already created migrations, no surprises.

Migrations are versioned files in your repo, so your database history lives next to your code history. Future you will be grateful.

A peek under the hood

So what really happens when you write this:

const u = await prisma.user.findUnique({ where: { email: "mia@cats.dev" } });

Roughly:

The Prisma Client (the generated JS) takes your call and builds a structured query, kind of like a JSON description of the request.
It sends that to the query engine, a small process or module that ships with Prisma.
The engine turns it into actual SQL for your database (Postgres, MySQL, SQLite, SQL Server, MongoDB, and so on).
It runs the SQL, gets the rows, and shapes them back into the typed object you expected.
You get a fully typed User (or null) back in your await.

That layered design is why Prisma can support different databases without changing your app code, and why the types are so accurate. The shape of every return value is computed from your schema and the exact select or include you used.

Tiny tips that will save you later

Run npx prisma studio when you want a quick GUI to peek at your data. It feels like cheating.
Keep one PrismaClient instance across your app. In dev with hot reload, stash it on globalThis so you do not open a hundred connections.
If a query feels slow, log the SQL with new PrismaClient({ log: ["query"] }) and see what is happening. Indexes still matter.
Use select aggressively in hot paths so you only fetch what you need.
Read the error messages. Prisma errors are weirdly nice.

Wrapping up

So that is the whole story. We wanted to stop wrestling with raw SQL. We built a translator. We taught it our database with schema.prisma. We generated a custom client called prisma. We agreed every call follows the same little shape:

prisma.<model>.<command>({ where, data, select, include, ... });

Read it as: client, then table, then verb, then a small form describing the details. That single shape covers reads, writes, updates, deletes, filters, sorts, pagination, and even joins.

Once that shape clicks, Prisma stops feeling like a library you are learning, and starts feeling like a translator you trust.

Happy querying, and give your pets a treat from me.

Learning MongoDB As If You Built It Yourself

Mohamed Idris — Thu, 21 May 2026 13:08:00 +0000

If you have ever tried to fit a messy real world thing into rigid SQL tables, you remember the feeling. A user has zero, one, or many addresses. Each address has a label, sometimes a unit number, sometimes notes. So you make an addresses table. Now every read needs a join. Then a customer feature ships that needs "favorite delivery instructions per address per day of the week", and your diagram grows three more boxes.

The shape of your data changed faster than your schema could keep up. Every change meant a migration, a deploy, and a small panic.

That is the gap MongoDB fills.

What is MongoDB, really

Think of MongoDB as a giant filing cabinet of folders. Each folder is a complete dossier on one thing. A user folder contains the user's name, their preferences, all their addresses, even their three latest orders if you want them right there. You do not have to open six folders and staple them together to learn about the user. Everything that belongs together lives together.

The folders are JSON like documents. The cabinet drawers are called collections. The cabinet itself is the database. There are no tables, no rigid columns, and no joins required for the common case. You ask for the folder, you get the folder.

The price for that flexibility is responsibility: the database is not going to enforce your schema for you unless you ask it to, and if you store data sloppily, you will read it back sloppily.

That is the whole vibe.

Let's pretend we are building one

We want a database that stores data the way our app already thinks about it (as nested objects), scales out across many machines, and lets us evolve schemas without crying. We will call it MongoDB.

For the running example, we are building a tiny recipe app. Recipes have ingredients, steps, tags, comments. Perfect for showing off documents.

Decision 1: The unit of data is a document, not a row

A document is a JSON object. (Internally, it is BSON, a binary form of JSON that adds types like Date, ObjectId, Decimal128, and binary blobs.) It can have arrays. It can have nested objects. It can be thirty fields deep. It is not a row.

{
  _id:    ObjectId("65fa1c..."),
  title:  "Mochi Cookies",
  author: "Mia",
  tags:   ["dessert", "japanese", "easy"],
  ingredients: [
    { name: "rice flour", amount: 200, unit: "g" },
    { name: "sugar",      amount: 80,  unit: "g" },
    { name: "milk",       amount: 250, unit: "ml" }
  ],
  steps: [
    "Mix dry ingredients.",
    "Add milk slowly while whisking.",
    "Cook on medium heat until smooth."
  ],
  prepMinutes: 20,
  createdAt:   ISODate("2026-04-01T10:00:00Z")
}

A few things worth pausing on:

Every document has an _id. If you do not provide one, the driver creates an ObjectId for you. It is sortable by time and unique across the cluster.
Schemas are flexible. Two recipes in the same collection do not need identical fields.
Arrays are first class. No "join table" needed for tags, steps, or ingredients on a recipe.
There is no enforced schema by default. This is a feature and a footgun. We will add validation in a moment.

Decision 2: Four verbs, just like SQL

The mental model is familiar. We just talk to documents instead of rows.

Insert

db.recipes.insertOne({
  title: "Mochi Cookies",
  author: "Mia",
  tags: ["dessert", "japanese"],
  prepMinutes: 20,
  createdAt: new Date(),
});

db.recipes.insertMany([
  { title: "Miso Soup",  prepMinutes: 10 },
  { title: "Onigiri",    prepMinutes: 15 },
]);

Find (the workhorse)

db.recipes.find({ tags: "dessert" });
db.recipes.findOne({ _id: ObjectId("65fa1c...") });
db.recipes.find({}, { projection: { title: 1, prepMinutes: 1 } }); // only those fields
db.recipes.find({ prepMinutes: { $lte: 15 } })
          .sort({ prepMinutes: 1 })
          .limit(10);

find returns a cursor. You stream from it. findOne returns one document or null.

Update

db.recipes.updateOne(
  { _id: ObjectId("65fa1c...") },
  { $set: { prepMinutes: 18 } }
);

db.recipes.updateMany(
  { tags: "japanese" },
  { $addToSet: { tags: "asian" } }
);

Notice the dollar prefixed operators. They are how you describe what to do, not the literal new document. If you write { $set: { x: 1 } }, you set field x. If you forget the operator and write just { x: 1 }, you replace the entire document with { x: 1 }. Yes, that bug stings the first time.

Delete

db.recipes.deleteOne({ _id: ObjectId("65fa1c...") });
db.recipes.deleteMany({ tags: "spam" });

Decision 3: Query operators, the dollar sign menu

Inside a query, MongoDB has a small language of operators. The greatest hits:

db.recipes.find({
  prepMinutes: { $gt: 10, $lte: 30 },
  tags:        { $in: ["dessert", "snack"] },
  author:      { $ne: "Anonymous" },
  createdAt:   { $gte: ISODate("2026-01-01") },
  notes:       { $exists: true },
});

The comparison operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin.

Logical operators (when AND of fields is not enough):

db.recipes.find({
  $or: [
    { prepMinutes: { $lt: 5 } },
    { tags: "easy" }
  ]
});

Querying inside arrays is shockingly useful:

// any ingredient with name "sugar"
db.recipes.find({ "ingredients.name": "sugar" });

// at least one ingredient with name "sugar" AND amount > 50, on the same element
db.recipes.find({
  ingredients: { $elemMatch: { name: "sugar", amount: { $gt: 50 } } }
});

// a recipe with all of these tags
db.recipes.find({ tags: { $all: ["easy", "dessert"] } });

Update operators are a parallel menu:

db.recipes.updateOne({ _id: id }, {
  $set:        { prepMinutes: 25 },
  $inc:        { views: 1 },
  $push:       { tags: "popular" },
  $addToSet:   { tags: "popular" },        // push but only if not already there
  $pull:       { tags: "draft" },
  $unset:      { temporaryNote: "" },
  $rename:     { oldField: "newField" }
});

If you remember three operators, remember $set, $inc, and $addToSet. You will reach for them every day.

Decision 4: Schema design, the part that actually matters

Here is the truth that catches every newcomer: in MongoDB, schema design is 90% of your job, even though there is no enforced schema. The flexibility is real, but the wrong shape is still going to hurt you.

The single most important decision is embed or reference.

Embed when data is owned and read together

A recipe owns its ingredients. They are not shared with other recipes. They are read every time you read the recipe. So embed them right inside the recipe document.

{
  title: "Mochi Cookies",
  ingredients: [
    { name: "rice flour", amount: 200, unit: "g" },
    { name: "sugar",      amount: 80,  unit: "g" }
  ]
}

One read, all the data. No joins. This is MongoDB's superpower.

Reference when data is shared or grows without bound

If a recipe is part of a cookbook, and a cookbook can have hundreds of recipes, you do not embed all the recipes inside the cookbook. You store the recipe ids:

// cookbooks
{ _id: ObjectId("c1"), title: "Tiny Asian Bites", recipeIds: [ObjectId("r1"), ObjectId("r2")] }

// recipes
{ _id: ObjectId("r1"), title: "Mochi Cookies", ... }

Then you fetch the recipes separately (or with $lookup, see the aggregation pipeline soon).

The rule of thumb

One to few: embed. (A user with 3 addresses.)
One to many but bounded and small: embed. (A blog post with 50 comments? Probably embed. With 5,000? Reference.)
One to many, unbounded or shared: reference.
Many to many: reference, with arrays of ids on one side or both.

There is also a maximum document size: 16 MB. If a document is approaching that limit, your model is wrong.

A few more design patterns that show up in production:

Bucket pattern: instead of one document per sensor reading per second, store one document per minute (or hour) holding an array of readings. Way fewer documents, better cache use, much faster aggregations.
Computed pattern: precompute aggregates and store them on the parent (commentCount, totalSpentCents). Update them on writes. The read becomes free.
Extended reference: when you reference, copy the few fields you almost always need (a recipe stores author: { _id, name, avatarUrl }). Saves a join. Trade off: you must update the copy when the source changes.
Schema versioning: store a schemaVersion: 2 field on every document. Migrating becomes "any document still on v1 gets transformed lazily on read".

These patterns are why senior MongoDB feels different from senior SQL. You design for the read, not the write.

Decision 5: Validate at the door anyway

Schemaless feels great until a typo in your code writes { tile: "Mochi" } instead of { title: "Mochi" } for three weeks before anyone notices. So MongoDB lets you bolt on JSON Schema validation at the collection level:

db.createCollection("recipes", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["title", "createdAt"],
      properties: {
        title:       { bsonType: "string", minLength: 1 },
        prepMinutes: { bsonType: "int", minimum: 0 },
        tags:        { bsonType: "array", items: { bsonType: "string" } },
        createdAt:   { bsonType: "date" }
      }
    }
  },
  validationLevel:  "strict",
  validationAction: "error"
});

Now writes that violate the schema are rejected. You keep the flexibility, you remove the typos.

In a real Node.js app, you usually go one level higher: define the schema once with Zod (or use Mongoose if you want a fuller ODM), and let it both validate at the API boundary and produce your TypeScript types.

Decision 6: Indexes work just like SQL, but read the rules

Without indexes, every query is a full collection scan. Same as SQL.

db.recipes.createIndex({ title: 1 });               // ascending
db.recipes.createIndex({ author: 1, createdAt: -1 }); // compound
db.recipes.createIndex({ email: 1 }, { unique: true });

Special index types you will actually use:

Multikey (automatic): if a field is an array, the index covers each element. db.recipes.createIndex({ tags: 1 }) lets you find recipes by any tag.
Text: full text search. db.recipes.createIndex({ title: "text", description: "text" }). Then find({ $text: { $search: "mochi" } }).
Geospatial (2dsphere): for "find places near me" queries on GeoJSON points.
TTL: documents auto delete after a deadline. Great for sessions, magic links, signed urls. db.sessions.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 }).
Partial: index only the matching subset. { partialFilterExpression: { active: true } }.
Wildcard: index unknown fields. Use sparingly.

To see what a query is doing, ask:

db.recipes.find({ tags: "dessert" }).explain("executionStats");

Look at winningPlan and the totalDocsExamined vs nReturned. If they are wildly different, you are probably scanning when you could be using an index.

The compound index ordering rule is the same as SQL: the order of fields matters. { author: 1, createdAt: -1 } helps queries that filter by author (alone) or by author plus createdAt. It does not help a query that only filters by createdAt. This is sometimes called the ESR rule in MongoDB land: index keys should generally appear in the order Equality, Sort, Range.

Decision 7: The aggregation pipeline, the real power tool

find is fine for "give me documents that match". The moment you need to group, transform, join, project, or compute, you graduate to the aggregation pipeline.

You think of it as Unix pipes. Each stage takes documents in and emits documents out.

db.orders.aggregate([
  { $match: { placedAt: { $gte: ISODate("2026-04-01") } } },
  { $group: {
      _id: "$customerId",
      orders: { $sum: 1 },
      revenueCents: { $sum: "$totalCents" }
  }},
  { $sort:  { revenueCents: -1 } },
  { $limit: 10 }
]);

The stages you will use most:

$match: filter, like WHERE. Put it first when you can to use indexes.
$project: shape the output, pick fields, compute new ones.
$group: collapse documents by a key, with accumulators ($sum, $avg, $min, $max, $push, $addToSet, $first, $last).
$sort, $limit, $skip: classic.
$unwind: turn an array field into one document per element. Magic for "explode tags".
$lookup: yes, MongoDB does joins. Same idea as SQL LEFT JOIN, with a slightly different API.
$facet: run multiple sub pipelines on the same input, return them side by side. Great for dashboards.
$set / $addFields: add computed fields without losing the existing ones.
$merge / $out: write the result back into a collection.

A $lookup example:

db.recipes.aggregate([
  { $match: { tags: "dessert" } },
  { $lookup: {
      from:         "users",
      localField:   "authorId",
      foreignField: "_id",
      as:           "author"
  }},
  { $unwind: "$author" },                  // flatten to a single object
  { $project: { title: 1, "author.name": 1, prepMinutes: 1 } }
]);

That is a join, an unwind, and a projection in one query. Once the pipeline clicks, you stop reaching for application code to do post processing. You let the database do it.

Senior tip: aggregations can use indexes, but only on the early $match and $sort stages. Filter early, then transform.

Decision 8: Transactions, when you really need them

For most workloads, the trick is to design your documents so a single write changes everything that needs to change. One document update is atomic by itself. That is enough for 90% of cases.

When you really do need to write across multiple documents or collections atomically, MongoDB has multi document transactions:

const session = client.startSession();
try {
  await session.withTransaction(async () => {
    await accounts.updateOne({ _id: a }, { $inc: { balance: -1000 } }, { session });
    await accounts.updateOne({ _id: b }, { $inc: { balance:  1000 } }, { session });
    await transfers.insertOne({ from: a, to: b, amountCents: 1000 }, { session });
  });
} finally {
  await session.endSession();
}

ACID is real here, just like in SQL. The catches:

Transactions need a replica set (which Atlas always gives you, and most production MongoDBs run as).
They are slower than single document writes. Reach for them only when you need them.
Long transactions hurt throughput. Keep them short.

The right design instinct in MongoDB is "make this one document update", and the second instinct is "okay then, transactions". Not the other way around.

Decision 9: Scaling, replication, and sharding

Three things you will hear about, in order of importance for most apps:

Replica set: a primary plus secondaries that follow along. Reads can go to secondaries with the right read preference. Writes go to the primary. If the primary dies, a secondary is elected. This gives you durability and high availability and is the default in Atlas.
Read concern and write concern: you choose how many nodes must acknowledge a write (w: "majority" is the safe default), and how recent your reads must be (readConcern: "majority" for the safest reads). These two knobs are the trade off between durability and latency.
Sharding: when one machine cannot hold the data, you split the collection across many. You pick a shard key that determines which documents live where. Pick wisely: an _id or random shard key spreads writes evenly, but lookups by user are then scattered across all shards. There is no perfect shard key, only the one that fits your access patterns.

Most apps under "huge" scale never need sharding. Replica sets are enough.

Decision 10: The modern stack

In 2026, the typical MongoDB setup looks like:

Atlas (the official managed service) for production. Free tier for prototypes. Handles replica sets, backups, point in time restore, monitoring, and Atlas Search.
Atlas Search for full text search backed by Lucene. It is wildly more capable than the built in $text operator.
Atlas Vector Search for semantic search and RAG (retrieval augmented generation) for AI apps. Vectors live next to your documents. One database, both kinds of search.
Official drivers for every language. In Node.js, the modern choice is the official mongodb driver, often paired with Zod for validation, or the Mongoose ODM if you want a more opinionated layer with hooks and middleware.
Compass (the GUI) for poking at data and prototyping aggregations.
mongosh (the new shell) for command line work.

If you are starting a new app, the lean default is: official driver + Zod schemas + Atlas. Reach for Mongoose only if you genuinely want its conveniences.

Decision 11: Pitfalls you only learn the hard way

A short list of senior level traps:

Forgetting $set in updates replaces the document. Always include the operator.
Storing a stringly typed _id when you could have used ObjectId. ObjectIds are sortable by creation time, smaller, and indexed by default.
Querying with the wrong type silently returns nothing. { price: "10" } will not match { price: 10 }. Types matter.
Letting documents grow unbounded. A recipe with 50,000 comments is a problem. Bucket or reference them.
Treating Mongo like SQL. If your queries are full of $lookup joins, you may be designing as if you are still in SQL. Reconsider whether the data should be embedded.
Writing find() and forgetting the projection. You ship the entire 8KB document over the wire when you only needed the title.
Skipping indexes "for now". "For now" becomes "in production" faster than you think.
Ignoring the _id in $group. _id: null groups everything together. _id: "$field" groups by that field. This is the most confusing line in the aggregation pipeline for newcomers.
Not using .lean() (Mongoose) or projection (driver) when you do not need full hydrated objects. Slower otherwise.
Treating capped collections like queues. Use a real queue.

A peek under the hood

What really happens when you run a query:

The driver opens a connection (pooled) to the cluster and figures out the topology (which node is primary, which are secondaries).
Your query goes to the appropriate node based on read preference.
The query planner picks an execution plan, ideally using an index.
The storage engine (WiredTiger, by default) reads pages from the cache or from disk. Documents are stored as compressed BSON.
Results stream back through the driver. Cursors fetch in batches by default (100 documents or 1MB), so a find() over a million docs does not blow up memory.
Writes go to the primary, get applied in memory, then flushed to the on disk journal, then replicated to secondaries based on your write concern.

The mental model is: WiredTiger is the SQLite or InnoDB underneath, BSON is the row format, and the replica set is the durability story. Once you know that, debugging slow queries and odd behavior gets much easier.

Tiny tips that will save you later

Design for the read. What does your most common query look like? Shape documents to make it one read, no joins.
Pick ObjectId for _id unless you have a reason not to.
Always set w: "majority" in production. Default is fine for development.
Use Atlas Search for anything past trivial text search.
Add indexes before they bite, not after. Watch slow query logs.
Use the aggregation pipeline. It is faster than fetching documents to your app and looping.
Keep documents under a megabyte where you can. 16 MB is the hard limit, but cache and replication love smaller documents.
Validate at the boundary with Zod (or the collection validator). Schemaless does not mean schema free.
Use .explain("executionStats") like you would EXPLAIN ANALYZE. It is the same skill in a different costume.
Back it up. Test the restore. Atlas does this for you. If you self host, you are on the hook.

Wrapping up

So that is the whole story. We were tired of forcing nested, evolving data into rigid tables. We built a database that stores documents, the same shape your app already passes around. We grouped them into collections, indexed them, and gave them a powerful aggregation pipeline so we did not have to do post processing in app code.

We accepted the trade off: schemaless is freedom, and freedom needs discipline. We designed documents around the reads we cared about, embedded what was owned, referenced what was shared, and added validation to keep typos from rotting our data. We learned that ACID is not just a SQL thing: single document writes are atomic, and full transactions are there when we need them.

Once that map is in your head, MongoDB stops feeling like SQL with weird syntax and starts feeling like the data model your app was always trying to be.

Happy modeling, and save a cookie for me.

Learning SQL As If You Built It Yourself

Mohamed Idris — Wed, 20 May 2026 13:08:00 +0000

If you have ever tried to keep your app's data in a JSON file or in memory, you know how that story ends. At first it works. Two users? Easy. A hundred users with orders, addresses, and a history of returns? Now your "database" is a 40MB file you are scared to open, and looking up a single record takes a full scan of the disk.

You start writing helper functions. Find a user by email. Find all their orders. Make sure no order points at a missing user. After a week of this, you have invented a worse, slower database, and you still cannot answer "what were our top 5 selling books last month?".

That is the gap SQL fills.

What is SQL, really

Think of SQL as a giant spreadsheet on steroids, with a strict librarian living inside. Your data goes into tables (sheets). Each row is a record. Each column has a type and rules. The librarian enforces the rules: no missing required fields, no duplicate ids, no orders pointing to a user that does not exist.

You do not poke around the sheets yourself. You write a polite question in a special language, and the librarian goes off, walks the shelves, and brings back exactly the rows you asked for. The question is declarative. You say what you want, not how to get it. The librarian (the query planner) figures out the fastest path.

That is the whole vibe.

Let's pretend we are building one

We want a way to store structured data, enforce rules between pieces of data, and answer questions about it without writing custom code every time. We will call the language SQL (Structured Query Language) and the engine behind it a relational database.

For our running example, we are opening a tiny online bookstore. Books, authors, customers, orders. We will model the whole thing and learn to ask it useful questions.

Decision 1: Data lives in tables, with a strict shape

A table has a fixed set of columns. Each column has a type. Each row must obey the shape. No "this row has an extra field" surprises.

CREATE TABLE authors (
  id          BIGSERIAL    PRIMARY KEY,
  name        TEXT         NOT NULL,
  born_year   INT
);

CREATE TABLE books (
  id          BIGSERIAL    PRIMARY KEY,
  title       TEXT         NOT NULL,
  author_id   BIGINT       NOT NULL REFERENCES authors(id),
  price_cents INT          NOT NULL CHECK (price_cents >= 0),
  published   DATE,
  created_at  TIMESTAMPTZ  NOT NULL DEFAULT now()
);

CREATE TABLE customers (
  id     BIGSERIAL PRIMARY KEY,
  email  TEXT      NOT NULL UNIQUE,
  name   TEXT      NOT NULL
);

CREATE TABLE orders (
  id          BIGSERIAL    PRIMARY KEY,
  customer_id BIGINT       NOT NULL REFERENCES customers(id),
  book_id     BIGINT       NOT NULL REFERENCES books(id),
  qty         INT          NOT NULL CHECK (qty > 0),
  placed_at   TIMESTAMPTZ  NOT NULL DEFAULT now()
);

A few things worth pausing on, because they show up everywhere:

PRIMARY KEY is the row's unique identity. Every table has one.
REFERENCES other_table(id) is a foreign key. The librarian will refuse to insert an order for a customer that does not exist, and refuse to delete a customer who still has orders (unless you say ON DELETE CASCADE).
NOT NULL, UNIQUE, CHECK are constraints that bake business rules into the data, not into the app code. The database becomes the last line of defense, even if six different apps write to it.
DEFAULT lets the database fill in values for you (timestamps, ids, version numbers).

This shape is the schema. The whole database is just schemas plus rows.

Quick sanity rule: if your data has a stable shape and relationships matter, use SQL. If your data is messy, document like, and varies row to row, that is what we will discuss in the MongoDB post.

Decision 2: Four verbs, infinite combinations

Every interaction with SQL is one of four verbs. Learn these and you have learned 70% of the language.

Insert

INSERT INTO authors (name, born_year)
VALUES ('Saint-Exupery', 1900);

INSERT INTO books (title, author_id, price_cents, published)
VALUES
  ('The Little Prince', 1, 999,  '1943-04-06'),
  ('Night Flight',      1, 1199, '1931-01-01');

Select (the workhorse)

SELECT id, title, price_cents
FROM   books
WHERE  price_cents < 1500
ORDER  BY published DESC
LIMIT  10;

Read it like English: pick these columns, from this table, where this is true, sorted this way, give me the first 10.

Update

UPDATE books
SET    price_cents = 1099
WHERE  id = 1;

If you forget the WHERE, you update every row. Yes, every senior has done it once. Wrap big updates in a transaction, we will see how soon.

Delete

DELETE FROM books WHERE id = 1;

Same warning as UPDATE. No WHERE, no rows left.

Decision 3: Filtering rows the librarian can understand

Inside WHERE you can stack conditions. A short list of the most useful operators:

SELECT * FROM books
WHERE  price_cents BETWEEN 800 AND 1500
   AND title       ILIKE '%prince%'        -- case insensitive in Postgres
   AND author_id   IN (1, 2, 3)
   AND published  IS NOT NULL
   AND published >= DATE '2000-01-01';

The classic gotcha: NULL is not equal to anything, not even itself. WHERE col = NULL always returns no rows. Use IS NULL and IS NOT NULL. Always.

LIKE 'foo%' matches the prefix foo. LIKE '%foo' matches the suffix. LIKE '%foo%' is the full text contains. The percent sign is the wildcard.

Decision 4: Joining tables, the actual superpower

Splitting data into multiple tables only pays off if we can stitch them back together at query time. That is what joins do.

The four flavors that matter:

-- INNER JOIN: only rows that match in both tables
SELECT b.title, a.name AS author
FROM   books b
JOIN   authors a ON a.id = b.author_id;

-- LEFT JOIN: every row from the left, with NULLs where the right has nothing
SELECT a.name, b.title
FROM   authors a
LEFT JOIN books b ON b.author_id = a.id;
-- An author with zero books still appears, with title = NULL.

-- RIGHT JOIN: mirror image of LEFT JOIN. Rarely used (just flip the tables).

-- FULL OUTER JOIN: every row from both sides, NULL where the other is missing.

The ON clause says how to match. The WHERE clause filters the joined result.

Two senior level rules that catch newcomers:

A LEFT JOIN plus a WHERE on the right table acts like an INNER JOIN. If you write LEFT JOIN books WHERE books.published IS NOT NULL, you have just thrown away the unmatched rows. Put filters that should keep the unmatched rows inside the ON clause: LEFT JOIN books b ON b.author_id = a.id AND b.published IS NOT NULL.
Always alias your tables in non trivial queries. b.title is much easier to read (and grep) than books.title repeated five times.

Decision 5: Aggregations, the "summarize this" verbs

When you do not want individual rows but a roll up, you reach for GROUP BY and the aggregate functions: COUNT, SUM, AVG, MIN, MAX.

-- Top selling books last month
SELECT b.id, b.title, SUM(o.qty) AS sold
FROM   orders o
JOIN   books  b ON b.id = o.book_id
WHERE  o.placed_at >= NOW() - INTERVAL '30 days'
GROUP  BY b.id, b.title
ORDER  BY sold DESC
LIMIT  5;

Two rules to internalize:

Every column in the SELECT must either be in the GROUP BY or wrapped in an aggregate.
HAVING filters groups. WHERE filters rows before grouping. Do not confuse them.

SELECT customer_id, COUNT(*) AS orders_count
FROM   orders
GROUP  BY customer_id
HAVING COUNT(*) >= 3;        -- only customers with 3+ orders

Decision 6: When one query is not enough, build it in pieces

For complex queries, stacking joins and aggregations gets unreadable fast. We added two tools for that.

Subqueries

A query inside a query. Treat its result as a virtual table.

SELECT title
FROM   books
WHERE  author_id IN (SELECT id FROM authors WHERE born_year < 1950);

Common Table Expressions (CTEs)

Same idea, named, top to bottom. Far more readable when the query has multiple stages.

WITH top_books AS (
  SELECT book_id, SUM(qty) AS sold
  FROM   orders
  WHERE  placed_at >= NOW() - INTERVAL '30 days'
  GROUP  BY book_id
)
SELECT b.title, t.sold
FROM   top_books t
JOIN   books b ON b.id = t.book_id
ORDER  BY t.sold DESC
LIMIT  5;

CTEs can be recursive, which is how you walk tree shaped data (categories with subcategories, employees with managers, comments with replies):

WITH RECURSIVE descendants AS (
  SELECT id, parent_id, name FROM categories WHERE id = 7
  UNION ALL
  SELECT c.id, c.parent_id, c.name
  FROM   categories c
  JOIN   descendants d ON d.id = c.parent_id
)
SELECT * FROM descendants;

CTEs read top to bottom like a small program. Use them.

Decision 7: Window functions, the senior superpower

Sometimes you want a per row calculation that "sees" other rows around it without collapsing into groups. That is what window functions do.

-- Rank books by sales within each author
SELECT
  b.author_id,
  b.title,
  SUM(o.qty) AS sold,
  RANK() OVER (
    PARTITION BY b.author_id
    ORDER BY SUM(o.qty) DESC
  ) AS rank_for_author
FROM books b
JOIN orders o ON o.book_id = b.id
GROUP BY b.author_id, b.title;

OVER(...) says "do this calculation across this window". PARTITION BY is the group, ORDER BY is the order within the group. You get one output row per input row, plus the calculated value.

Common ones to know:

ROW_NUMBER() for "give each row a serial number".
RANK() and DENSE_RANK() for tied ranking.
LAG(col), LEAD(col) for "value of the previous/next row in the window".
SUM(col) OVER (ORDER BY ...) for running totals.

Once these click, a whole class of "I had to do this in app code" problems become one liners.

Decision 8: Indexes, the secret to fast queries

A table without indexes is a phone book printed in random order. Finding "Alice" means starting at page one. With an index, the librarian builds an alphabetical map: "Alice is around page 47, go straight there".

CREATE INDEX books_author_id_idx ON books (author_id);
CREATE INDEX orders_customer_placed_idx ON orders (customer_id, placed_at DESC);
CREATE UNIQUE INDEX customers_email_idx ON customers (email);

The senior level rules:

Primary keys and unique constraints already create indexes. You get those free.
Index columns you filter or join on, not columns you only display.
Composite index column order matters. (customer_id, placed_at) helps queries that filter by customer_id (alone) or by customer_id plus placed_at. It does not help a query that only filters by placed_at.
Postgres has special index types: GIN (for arrays and JSONB), BRIN (for huge time series), partial (WHERE active = true), expression (LOWER(email)).
Indexes are not free. Every write has to update them. Do not index every column "just in case". Profile first.

To find out what the database is actually doing for a query, ask:

EXPLAIN ANALYZE
SELECT * FROM books WHERE author_id = 1;

That returns the query plan. Look for "Index Scan" (good) versus "Seq Scan" (full table read, fine for small tables, scary for big ones), and look at the actual time per step.

Reading query plans is the single skill that separates "writes SQL" from "writes fast SQL". Spend time on it.

Decision 9: Transactions, all or nothing

Sometimes a single user action needs multiple statements, and "half done" is the worst possible state. Money moved out of one account but never into the other. An order created without payment.

We wrap the statements in a transaction. Either every statement commits, or none of them do.

BEGIN;

UPDATE accounts SET balance = balance - 1000 WHERE id = 1;
UPDATE accounts SET balance = balance + 1000 WHERE id = 2;

COMMIT;        -- or ROLLBACK if anything went wrong

Transactions guarantee four properties together known as ACID:

Atomicity: all or nothing.
Consistency: constraints stay valid before and after.
Isolation: concurrent transactions do not see each other's half done work.
Durability: once committed, it survives a crash.

Isolation has levels (read committed, repeatable read, serializable). The default in Postgres is READ COMMITTED, which is fine for most apps. Reach for SERIALIZABLE when you have a critical multi step invariant and you would rather have the database retry than risk anomalies. Read about phantom reads and lost updates once, then you will recognize the bug shapes when you see them.

Decision 10: Views and materialized views

If a complex query is something you ask all the time, give it a name.

CREATE VIEW top_books_30d AS
SELECT b.id, b.title, SUM(o.qty) AS sold
FROM   orders o
JOIN   books  b ON b.id = o.book_id
WHERE  o.placed_at >= NOW() - INTERVAL '30 days'
GROUP  BY b.id, b.title;

SELECT * FROM top_books_30d ORDER BY sold DESC LIMIT 5;

A view is just a saved query. It runs every time you SELECT from it.

A materialized view stores the result physically and refreshes on demand. Great for expensive analytics that do not need to be real time.

CREATE MATERIALIZED VIEW top_books_30d AS ...;
REFRESH MATERIALIZED VIEW top_books_30d;

Decision 11: Set operations

Less famous, but very handy.

-- Books either by author 1 or with sales (and both)
SELECT id FROM books WHERE author_id = 1
UNION
SELECT book_id FROM orders;

-- Same idea but keep duplicates
UNION ALL

-- In A but not in B
EXCEPT

-- In both
INTERSECT

UNION deduplicates and is slower. UNION ALL keeps everything and is faster. Pick on purpose.

Decision 12: Talking to SQL safely from your app

This is the one rule you must never break.

Never build a query by string concatenation with user input. That is how you get SQL injection, the most embarrassing bug in our profession.

// NEVER
db.query(`SELECT * FROM users WHERE email = '${email}'`);

// ALWAYS
db.query("SELECT * FROM users WHERE email = $1", [email]);

Use parameterized queries. Every modern client supports them. The driver sends the SQL and the values separately, so the database never confuses one for the other.

The other classic app side trap is the N+1 query problem. You fetch a list of authors, then for each one, you fire a separate query for their books. 1 query becomes 1 + N queries. The fix is one query with a JOIN, or batch loading by id list (WHERE author_id IN (...)).

Decision 13: Designing schemas that age well

The art is in the schema, not the queries. Tables you regret are tables you fight forever. A short senior level checklist:

Normalize first, denormalize on purpose. A normalized schema (no duplicated facts) is easier to keep correct. You can always add a denormalized cache column later if profiling demands it.
Pick the right primary key. BIGSERIAL (auto increment) is fine for most things. UUIDs are great for distributed systems and for not exposing row counts in URLs. Use UUID v7 if you need sortable UUIDs.
Always store timestamps with timezone. TIMESTAMPTZ, not TIMESTAMP. Future you will thank present you.
Money in integer cents, not floats. 1.10 + 2.20 in floats is heartbreak.
Booleans are fine. Do not use a CHAR(1) "Y"/"N". This is not 1995.
Add indexes for foreign keys. The database does not always do this for you, and queries that join on them will sit and cry without one.
Soft delete with a deleted_at TIMESTAMPTZ column if you need recoverable deletes. Then add WHERE deleted_at IS NULL to your reads (or a partial index).
Migrations are version controlled SQL. Tools like Flyway, Sqitch, Prisma Migrate, Alembic. Never edit the production schema by hand.

Decision 14: A peek under the hood

What really happens when you run a query:

The client sends the SQL to the server (bind parameters separately if you used a parameterized query).
The parser turns the text into a syntax tree.
The planner / optimizer considers many possible execution plans (full scan, index scan, different join orders, hash join vs merge join vs nested loop). It uses statistics about the table sizes and column distributions to pick the cheapest plan it can find.
The executor runs the chosen plan, reading pages from disk or the buffer cache, joining, filtering, aggregating.
Results stream back to the client. Transactions wrap all of this in WAL (write ahead log) entries for durability.

That little planner is the brain of the whole thing. It is also why the same query can be fast on Tuesday and slow on Wednesday: the data shape changed, and the planner picked a different plan. Keep statistics fresh (ANALYZE in Postgres) and you will rarely be surprised.

A short guide to dialects

SQL is a standard. Real engines extend and tweak it. The big three you will see:

PostgreSQL: the senior favorite. Best in class JSON support, window functions, CTEs, generated columns, partial indexes, RETURNING, extensions. Default choice for most new apps in 2026.
MySQL / MariaDB: massive ecosystem, fine performance, weaker default constraints (set STRICT_ALL_TABLES), historically weaker on JSON and window features (now caught up).
SQLite: a single file database, perfect for embedded use, tests, mobile, and surprisingly capable for small to mid sized apps. Great for prototypes.

Almost every example in this post is portable. The places you will find dialect differences: identifier quoting, auto increment syntax, JSON functions, full text search, and date functions.

Tiny tips that will save you later

SELECT * is fine in the editor, dangerous in production code. List the columns you need.
Always run an UPDATE or DELETE as a SELECT first. Same WHERE, same eyes.
Wrap risky changes in a transaction with BEGIN; ... ROLLBACK; until you are certain.
COUNT(*) counts rows. COUNT(col) skips NULLs. They are different.
Prefer EXISTS over IN for subqueries that may grow large.
Filter early. Push WHERE and joins as low as possible so fewer rows climb the pipeline.
Read the query plan before optimizing. Guessing is a waste of an evening.
Connection pool, do not connect per request. Use PgBouncer, the language client's built in pool, or your framework's helper.
Put long names into a style guide. snake_case for tables and columns, plural for tables (books, not book). Pick one and never argue about it again.
Back up the database. Test the restore. A backup you have never restored is a wish, not a backup.

Wrapping up

So that is the whole story. We were tired of inventing tiny worse databases out of files and helper functions. We built one engine that holds structured data, enforces relationships, and answers questions in a declarative language we agreed to call SQL.

We taught the engine four verbs: INSERT, SELECT, UPDATE, DELETE. We let it stitch tables back together with joins, summarize with aggregations, and walk windows with window functions. We added CTEs so complex queries read top to bottom. We made it fast with indexes, and gave it transactions and ACID guarantees so half done work is never visible. We baked rules into the schema with constraints, so the data stays sane even when buggy apps try to mess it up.

Once that map is in your head, every database tutorial, blog post, and codebase starts to feel familiar. SQL stops feeling like a foreign language and starts feeling like a calm conversation with a very picky librarian who is, secretly, on your side.

Happy querying, and put a bookmark in chapter two for me.

Learning Frontend Testing As If You Built It Yourself

Mohamed Idris — Tue, 19 May 2026 13:07:00 +0000

If you have ever pushed a "tiny" change to production on a Friday and watched the bug reports roll in over the weekend, you know why testing exists. Manual checking does not scale. A teammate refactors a util, your screen still looks fine, and three pages you never opened are quietly broken.

Tests are how you stop being scared of your own code.

That is the gap testing fills.

What is frontend testing, really

Think of tests as a tiny robot that opens your app for you, faster and more thorough than you ever could. The robot clicks, types, waits, asserts. It does this on every commit. When something breaks, the robot tells you within seconds.

There are three sizes of robot, and a senior frontend engineer uses all three on purpose:

Unit tests poke a single function. Tiny, fast, run by the thousands.
Component / integration tests mount one component (or a small tree) and interact with it. Real DOM, real events, mocked network.
End to end tests drive a real browser through a real app. Slow, expensive, the closest thing to a user.

The 2026 sweet spot in the React world: Vitest for the first two, Playwright for the third. React Testing Library for the assertions and queries inside Vitest.

That is the whole vibe.

Let's pretend we are building one

We want a frontend testing setup that is fast in development, accurate in CI, and gives us confidence to refactor without panic. We will not build it from scratch. We will assemble it from three modern tools.

For the running example, we are testing pieces of an "Adopt a cat" app: a formatPrice helper, an AdoptForm component, and the full happy path of finding and adopting a cat.

Decision 1: Three layers, three tools

┌─────────────────────────────────────────────────┐
│  E2E tests           Playwright          ~few   │
│  ──────────────                                  │
│  Component tests     Vitest + RTL        ~many  │
│  ──────────────                                  │
│  Unit tests          Vitest              ~lots  │
└─────────────────────────────────────────────────┘

The number of tests should look roughly like that triangle. Lots of cheap unit tests, a healthy middle of component tests, a small number of expensive E2E tests for the critical paths.

The trap senior engineers warn about: a flat shape, where you have hundreds of E2E tests and almost no unit or component tests. Your CI takes 40 minutes, every flaky test wastes the team's morning, and a small refactor breaks 60 tests at once.

Decision 2: Unit tests with Vitest

Install:

npm i -D vitest

Add to package.json:

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:cov": "vitest run --coverage"
  }
}

A unit test is a function that calls another function and asserts the result.

// src/lib/format-price.ts
export function formatPrice(cents: number): string {
  return `$${(cents / 100).toFixed(2)}`;
}

// src/lib/format-price.test.ts
import { describe, it, expect } from "vitest";
import { formatPrice } from "./format-price";

describe("formatPrice", () => {
  it("formats whole dollars", () => {
    expect(formatPrice(500)).toBe("$5.00");
  });

  it("formats cents with two decimals", () => {
    expect(formatPrice(1234)).toBe("$12.34");
  });

  it("handles zero", () => {
    expect(formatPrice(0)).toBe("$0.00");
  });
});

A few things worth knowing:

describe groups related tests, it (or test) is one test.
expect(x).toBe(y) checks strict equality. .toEqual(y) for deep equality. .toBeTruthy(), .toContain(), .toThrow() for the rest.
Vitest uses Vite's config, so your aliases, plugins, and TypeScript setup work for free.
Tests run in parallel by default, so write them isolated. No shared global state.

The senior level habits:

Test the contract, not the implementation. Same input, same output. Refactors should not break unit tests.
One assertion per test in spirit. A test that checks five different things is five tests in a trench coat.
Name tests as sentences. "formats whole dollars" reads better than "test1".
Skip happy path snapshots. A snapshot of a function output is fine. A snapshot of a 200 line HTML tree is a tax you will pay forever.

Decision 3: Component tests with React Testing Library

Install:

npm i -D @testing-library/react @testing-library/user-event @testing-library/jest-dom jsdom

Configure Vitest for the DOM:

// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    setupFiles: ["./test/setup.ts"],
    globals: true,
  },
});

// test/setup.ts
import "@testing-library/jest-dom/vitest";

Now you can mount components and interact with them:

// src/components/AdoptForm.tsx
"use client";
import { useState } from "react";

export function AdoptForm({ onAdopt }: { onAdopt: (name: string) => void }) {
  const [name, setName] = useState("");
  return (
    <form onSubmit={(e) => { e.preventDefault(); if (name) onAdopt(name); }}>
      <label htmlFor="name">Cat name</label>
      <input id="name" value={name} onChange={(e) => setName(e.target.value)} />
      <button type="submit" disabled={!name}>Adopt</button>
    </form>
  );
}

// src/components/AdoptForm.test.tsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, it, expect, vi } from "vitest";
import { AdoptForm } from "./AdoptForm";

describe("AdoptForm", () => {
  it("disables the submit button when the name is empty", () => {
    render(<AdoptForm onAdopt={vi.fn()} />);
    expect(screen.getByRole("button", { name: /adopt/i })).toBeDisabled();
  });

  it("calls onAdopt with the typed name", async () => {
    const user    = userEvent.setup();
    const onAdopt = vi.fn();
    render(<AdoptForm onAdopt={onAdopt} />);

    await user.type(screen.getByLabelText(/cat name/i), "Mochi");
    await user.click(screen.getByRole("button", { name: /adopt/i }));

    expect(onAdopt).toHaveBeenCalledWith("Mochi");
  });
});

The single most important rule of React Testing Library:

Find elements the way a user would. By role, by label, by visible text. Almost never by class name or test id.

The query priority, from best to worst:

getByRole (button, heading, textbox, link, ...). Tests both rendering and accessibility.
getByLabelText for form fields.
getByPlaceholderText, getByText, getByDisplayValue.
getByAltText, getByTitle for images and tooltips.
getByTestId as a last resort.

If your tests cannot find a button by its role, that is a sign the markup is not accessible. Tests guide you toward better HTML.

The four flavors of query:

getBy... throws if not found. Use for things that should be there now.
queryBy... returns null if not found. Use for asserting absence: expect(queryByText("Loading")).toBeNull().
findBy... is async, retries until it appears. Use for things that show up after a state change or a fetch.
...All versions return arrays for matching multiple.

Decision 4: Mocking the network, the right way

Real components fetch data. In tests you do not want to hit a real API. Two modern choices:

MSW (Mock Service Worker), the senior favorite

MSW intercepts fetch calls at the network layer, so your component code uses real fetch but the response comes from your handlers.

// test/mocks.ts
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";

export const handlers = [
  http.get("/api/cats", () =>
    HttpResponse.json([{ id: "1", name: "Mochi" }])
  ),
  http.post("/api/adopt/:id", () => HttpResponse.json({ ok: true })),
];

export const server = setupServer(...handlers);

// test/setup.ts
import { server } from "./mocks";
import { beforeAll, afterAll, afterEach } from "vitest";

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Now any fetch("/api/cats") in any test returns the mocked data. You can override per test:

import { http, HttpResponse } from "msw";
import { server } from "../test/mocks";

it("shows an error when the API fails", async () => {
  server.use(http.get("/api/cats", () => new HttpResponse(null, { status: 500 })));
  // ...
});

MSW is the closest thing to "real network" you can get without one. The same handlers work in dev (with the browser worker), in tests (with the Node server), and in Storybook.

Module mocks for everything else

For non network dependencies, use Vitest's vi.mock:

import { vi } from "vitest";

vi.mock("@/lib/db", () => ({
  db: { post: { findMany: vi.fn().mockResolvedValue([]) } }
}));

Use sparingly. A test full of mocks tests the mocks, not the code.

Decision 5: End to end tests with Playwright

Install:

npm init playwright@latest

Playwright spins up real Chromium, Firefox, and WebKit, drives them through your app, and asserts what the user sees. It is the gold standard for E2E in 2026.

A single test of the adoption flow:

// e2e/adopt.spec.ts
import { test, expect } from "@playwright/test";

test("a user can adopt a cat", async ({ page }) => {
  await page.goto("/cats");

  await expect(page.getByRole("heading", { name: /cats looking for a home/i })).toBeVisible();
  await page.getByRole("button", { name: "Adopt Mochi" }).click();

  await expect(page.getByText("Mochi is going home")).toBeVisible();
  await expect(page).toHaveURL(/\/cats\/adopted/);
});

The senior level habits:

Use the same query priorities as RTL. getByRole, getByLabel, getByText. Skip CSS selectors when you can.
Web first assertions auto retry. await expect(locator).toBeVisible() keeps trying until the timeout. Almost no waitForSelector needed.
Test the critical path, not every page. 20 to 30 well chosen E2E tests is plenty for most apps. The unit and component layers cover the rest.
Run against a real build (next build && next start) in CI, not the dev server. You catch problems specific to production builds (missing "use client", env var issues, route handler bugs).
Shard E2E in CI. Playwright supports --shard=1/4 natively. Splitting the suite across four parallel runners turns a 12 minute run into 3.
Trace on failure. npx playwright test --trace=retain-on-failure records a video, screenshots, and network for every failing test. Debugging gets ten times faster.

A few useful Playwright extras:

await page.locator("input[name=name]").fill("Mochi");      // fill a field
await page.getByRole("button", { name: "Adopt" }).click(); // click
await page.waitForURL("/dashboard");                       // wait for navigation
await page.screenshot({ path: "fail.png" });               // screenshot on demand

await expect(page.getByText("Loading")).toHaveCount(0);    // assert it disappeared
await expect(page.getByRole("alert")).toContainText("Saved");

For visual regression, Playwright has a built in toHaveScreenshot() that diffs against a stored baseline. Great for design system primitives.

Decision 6: A modern test pyramid for a real React app

A repeatable target for any new project:

unit:                lots                tests/lib/**/*.test.ts
component:           per feature         tests/components/**/*.test.tsx
e2e:                 critical paths      e2e/**/*.spec.ts

What to test where:

Pure functions, formatters, parsers, validators: unit.
Single component behavior with props and events: component.
A page or a feature working end to end (auth, checkout, signup, search): E2E.
Server actions, API routes, server queries: integration tests with a real test database (or a transactional rollback per test). Use Vitest with node environment, not jsdom.
Skip: testing internal state, testing your component library, testing TypeScript types, testing third party hooks.

Decision 7: Make tests easy to read

The single best style guide for tests, in one rule:

A failing test should tell you what is wrong without you reading the code.

Two patterns help:

Arrange / Act / Assert

it("calls onAdopt with the typed name", async () => {
  // Arrange
  const user    = userEvent.setup();
  const onAdopt = vi.fn();
  render(<AdoptForm onAdopt={onAdopt} />);

  // Act
  await user.type(screen.getByLabelText(/cat name/i), "Mochi");
  await user.click(screen.getByRole("button", { name: /adopt/i }));

  // Assert
  expect(onAdopt).toHaveBeenCalledWith("Mochi");
});

Custom render helpers

Wrap once, reuse everywhere. Providers (router, query client, theme, i18n) live in one place:

// test/render.tsx
import { render } from "@testing-library/react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

export function renderWithProviders(ui: React.ReactElement) {
  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
  return render(<QueryClientProvider client={qc}>{ui}</QueryClientProvider>);
}

Now every component test imports renderWithProviders and the noise stays out of the test body.

Decision 8: Testing async UI without flakes

Async tests fail intermittently when they assert at the wrong moment. The fix is to ask the testing library to wait for the right thing:

// wait for a thing to appear
expect(await screen.findByText("Adopted")).toBeInTheDocument();

// wait for a thing to disappear
await waitForElementToBeRemoved(() => screen.queryByText("Loading"));

// wait for any condition
await waitFor(() => {
  expect(onAdopt).toHaveBeenCalled();
});

Two anti patterns to avoid:

setTimeout or hand spun delays. Always flaky.
Testing useEffect directly. Test the user visible result, not the hook internals.

Decision 9: CI integration and speed

A CI pipeline that respects developers:

# .github/workflows/test.yml (sketch)
test:
  - run: npm ci
  - run: npm run lint
  - run: npm run test:run -- --reporter=github
  - run: npx playwright install --with-deps
  - run: npm run build
  - run: npx playwright test --shard=${{ matrix.shard }}/4

The order matters: lint first (cheapest), unit and component tests next (fast), build, then E2E (slowest, sharded).

The senior level habits:

Fail fast. If lint fails, do not run E2E.
Cache dependencies. actions/setup-node plus cache: npm shaves real time.
Upload Playwright traces as artifacts on failure. Future you will thank present you.
Ban .only and .skip in CI with a lint rule. They sneak in.

Decision 10: Senior level moves and pitfalls

A short list of habits that separate "writes tests" from "writes good tests":

Test behavior, not structure. A test that breaks when you change the markup but not the behavior is testing too much.
Avoid data-testid unless you must. They drift from the user experience.
Write the test first when the bug is hard. A failing test pinpoints the problem and stays as a regression guard.
Never test third party libraries. They have their own tests.
Test the boundary, not the internals. A component takes props, renders, and emits events. Test those.
Keep tests independent. Order should not matter. No shared mutable state.
Mock at the network, not at every module. MSW > a forest of vi.mock.
Run a real database in integration tests. SQLite in memory, Postgres in Docker, Mongo Memory Server. Mocked databases lie.
Coverage is not a goal. 80 high quality tests beat 200 noisy ones.
Delete tests that no longer earn their keep. A test you mute every other week is a tax, not an asset.

A peek under the hood

What really happens when you run vitest:

Vitest reads your vite.config and starts a Vite dev server.
Vite transforms your source on the fly using esbuild or SWC.
Tests run in worker threads, in parallel.
JSDOM provides a fake DOM. React renders into it. Events go through React's synthetic event system.
Assertions run, results stream to the reporter.

What really happens when you run Playwright:

Playwright launches a real browser binary (Chromium by default).
It opens your test URL in a fresh context (cookies, storage are isolated).
Each await is an action recorded in a trace, with snapshots and network logs.
Tests run in parallel across browser contexts within a single browser instance.
On failure, traces are saved, screenshots are taken, the next test still runs.

Two consequences for your time:

Vitest is fast because Vite is fast. Cold start in milliseconds, hot reload of tests as you edit.
Playwright is slow because browsers are slow. Use it sparingly, run in parallel, shard in CI.

Tiny tips that will save you later

screen.debug() prints the current DOM. Use it when you cannot find a node.
logRoles(container) lists every accessible role. Pick the one your test should query.
Use userEvent, not fireEvent. It simulates real user actions including focus, keypresses, and accessible interactions.
Reset MSW handlers between tests. Otherwise tests bleed into each other.
Run Playwright in --ui mode locally. The time travel debugger is magical.
Snapshot only stable, narrow output. A function output, a serialized state. Not a 5000 character DOM string.
Write a small renderWithProviders on day one. Tests stay lean.
Keep one test file per source file, named the same way (Foo.tsx paired with Foo.test.tsx). Easy to find.

Wrapping up

So that is the whole story. We were tired of being scared of our own code. We built a three layer testing pyramid: lots of unit tests with Vitest, a healthy middle of component tests with React Testing Library, a small number of E2E tests with Playwright. We mocked the network with MSW, queried elements the way a user would, asserted behavior instead of internals, and let CI catch what we missed.

We learned to write tests as sentences, structure them as Arrange / Act / Assert, keep them independent, and delete the ones that stopped earning their keep. We chose tools that pay back our time: Vitest for speed, RTL for accessibility friendly queries, Playwright for real browser confidence, MSW for sane network mocks.

Once that map is in your head, tests stop feeling like a tax and start feeling like a backup brain that catches the regressions a tired Friday you would have shipped. You start refactoring without flinching. You start sleeping better.

Happy testing, and may your suite stay green.

Learning Web Performance As If You Built It Yourself

Mohamed Idris — Mon, 18 May 2026 13:06:00 +0000

If you have ever opened a beautiful new website on your phone and watched the layout shift around for two seconds while you tried to tap a button, you have met bad web performance. You are not alone. According to the 2025 Web Almanac, only 48% of mobile pages and 56% of desktop pages pass all three Core Web Vitals.

Performance is the gap between "the design looks great" and "people actually use it". A 24% lower bounce rate is the kind of number a CEO will print on a poster. It comes from making the page feel fast.

That is the gap web performance fills.

What is web performance, really

Think of web performance as measuring three feelings the user has, not measuring how clever your code is:

"Did the page show up?" (LCP, Largest Contentful Paint)
"Does it respond when I tap?" (INP, Interaction to Next Paint)
"Is it staying still or jumping around?" (CLS, Cumulative Layout Shift)

Google calls these Core Web Vitals. They are user perception metrics, not synthetic numbers. Google measures them on real users. They feed search rankings. Browsers expose them via the Performance API for free.

The 2026 thresholds you must memorize:

Metric	Good	Needs work	Poor
LCP	≤ 2.5 s	2.5 to 4.0 s	> 4.0 s
INP	≤ 200 ms	200 to 500 ms	> 500 ms
CLS	≤ 0.1	0.1 to 0.25	> 0.25

INP replaced FID (First Input Delay) in March 2024 and is the strictest Core Web Vital. 43% of sites fail the 200ms INP threshold. Most of the work in 2026 is here.

That is the whole vibe.

Let's pretend we are building one

We want a way to make websites feel fast on real devices, on real networks, in real users' hands. We will not invent the metrics. The browser already gives them to us. We just need to learn to read them and to fix what they reveal.

For the running example, we are speeding up a tiny online bakery landing page: a hero image, a list of products, a "buy" button. We will improve each metric in turn.

Decision 1: Measure first, optimize second

Before you change anything, measure. Three places to measure, in order:

Lighthouse / PageSpeed Insights

Open Chrome DevTools, hit the Lighthouse tab, run a report. Or paste your URL into pagespeed.web.dev. You get scores for each metric, plus specific suggestions ranked by impact.

This is lab data, run on a simulated mobile device. Useful for catching regressions, but does not match what real users see.

CrUX (Chrome User Experience Report)

Real anonymized data from real Chrome users. The PageSpeed report shows it at the top under "field data". This is the data Google uses for ranking. Trust this number more than the Lighthouse one.

Real User Monitoring (RUM)

Send your own metrics from production using the web-vitals library. Two minutes of setup gives you the truth, on every device, every connection, every page.

import { onLCP, onINP, onCLS } from "web-vitals";

function send(metric) {
  // ship to your analytics endpoint
  navigator.sendBeacon("/api/vitals", JSON.stringify(metric));
}

onLCP(send);
onINP(send);
onCLS(send);

The senior level rule: Lighthouse for trends, CrUX for the truth, RUM for debugging.

Decision 2: Improve LCP, the "did the page show up" metric

LCP measures the time until the largest visible element finishes rendering. Almost always: a hero image, a hero <h1>, or a big text block. If LCP is slow, the page feels broken even if everything else is fine.

The four highest impact fixes, in order:

Preload the LCP image

Tell the browser the most important image early, while it is still parsing HTML.

<link
  rel="preload"
  as="image"
  href="/hero-bakery.jpg"
  fetchpriority="high"
/>

In Next.js, priority on <Image> does the same thing:

<Image src="/hero-bakery.jpg" alt="..." width={1200} height={800} priority />

Use modern image formats and responsive sizes

AVIF is roughly half the size of JPEG. WebP is roughly 25% smaller. Browsers support them. Serve them.

<picture>
  <source srcset="/hero.avif" type="image/avif" />
  <source srcset="/hero.webp" type="image/webp" />
  <img src="/hero.jpg" alt="..." width="1200" height="800" />
</picture>

Always serve a size that fits the viewport. A phone does not need a 4K hero. Use srcset with descriptors:

<img
  src="/hero-1200.jpg"
  srcset="/hero-400.jpg 400w, /hero-800.jpg 800w, /hero-1600.jpg 1600w"
  sizes="(max-width: 600px) 100vw, 1200px"
  alt="..."
/>

A tool like Sharp or a CDN like Cloudinary or Vercel Image Optimization gives you these sizes automatically.

Inline critical CSS, defer the rest

Render blocking CSS delays paint. Inline the styles your above-the-fold content needs in <style>, then load the full stylesheet <link rel="preload" as="style"> and apply asynchronously.

Most teams do not do this by hand. Frameworks handle it. If yours does not, run a tool like Critters or use a service that does.

Server side render the first paint

Static HTML (SSG, ISR, RSC, plain server rendering) puts visible content on the screen before any JavaScript executes. That is the single biggest win you will ever ship.

If your app is a Vite SPA where everything renders inside <div id="root"></div> on the client, your LCP is at the mercy of the JS bundle. If you can move to Next.js, Astro, Remix, or a framework that ships HTML, do.

Self host fonts and use `font-display: swap`

A custom font that takes 800ms to load and blocks text with font-display: block will torpedo your LCP. The fix:

@font-face {
  font-family: "Inter";
  src: url("/fonts/inter.woff2") format("woff2");
  font-display: swap;
  font-weight: 100 900;  /* variable font, one file for all weights */
}

font-display: swap shows fallback text immediately and swaps to the custom font when it loads. Then preload the file:

<link rel="preload" as="font" type="font/woff2" href="/fonts/inter.woff2" crossorigin />

Better yet, use next/font (in Next.js) or unplugin-fonts (everywhere else). They handle subsetting, preloading, and size-adjust to prevent CLS when the font swaps.

Decision 3: Improve INP, the "does it respond" metric

INP is the time between a user interaction (tap, click, keypress) and the next paint after the resulting work. If your button takes 600ms to react, INP fails.

The pain almost always comes from a long task on the main thread blocking the browser from painting. JavaScript is single threaded. While it is busy, nothing else happens.

The senior level fixes:

Break long tasks into chunks

A 200ms for loop blocks the main thread for 200ms. Split it.

async function processInChunks<T>(items: T[], handle: (item: T) => void) {
  const CHUNK = 50;
  for (let i = 0; i < items.length; i += CHUNK) {
    items.slice(i, i + CHUNK).forEach(handle);
    await new Promise((r) => setTimeout(r, 0)); // yield to the browser
  }
}

Or use the modern API directly:

async function yieldToMain() {
  if ("scheduler" in window && "yield" in window.scheduler) {
    return window.scheduler.yield();
  }
  return new Promise((r) => setTimeout(r, 0));
}

Inside long work, await yieldToMain() periodically. The browser gets a chance to paint and respond.

Use React's transitions for non urgent updates

Sometimes the work is React rendering. useTransition marks an update as low priority so the browser can paint the urgent stuff first.

const [isPending, startTransition] = useTransition();

function handleSearch(query: string) {
  setQuery(query);                          // urgent: input updates immediately
  startTransition(() => setResults(filter(allItems, query))); // not urgent
}

The input feels instant even when the result list is heavy.

Move heavy work off the main thread

If a function takes 400ms, it should not run on the UI thread. Use a Web Worker:

// worker.ts
self.onmessage = (e) => {
  const result = expensiveCompute(e.data);
  self.postMessage(result);
};

// main.ts
const worker = new Worker(new URL("./worker.ts", import.meta.url), { type: "module" });
worker.postMessage(input);
worker.onmessage = (e) => setResult(e.data);

Tools like comlink make this much friendlier (the worker exposes a function, you await it from the main thread).

Cut your JavaScript bundle

The fastest function is the one that does not run. Common wins:

Code split by route. Next.js does this automatically. In Vite SPAs, React.lazy plus a route loader does the trick.
Lazy load heavy widgets. Maps, charts, rich text editors should load only when used.
Tree shake your icon libraries. Importing a single icon from lucide-react is fine. Importing the whole namespace is not.
Replace heavy dependencies. date-fns/locale/en over moment. nanoid over uuid.
Use the Coverage tab in DevTools to see how much of your shipped JS is actually used. The number will surprise you.

Stop unnecessary re renders

A React component that re renders on every keystroke when it does not need to is INP poison. Tools to reach for:

React.memo on heavy components passed stable props.
useMemo for expensive computations.
useCallback only when the callback is a dependency of a memoed child.
The React Compiler (in 2026) handles most of this for you, but it is not magic. Inspect with the React DevTools Profiler.

Decision 4: Improve CLS, the "is it staying still" metric

CLS measures unexpected layout shifts: the page jumping while the user is reading or about to tap. Three causes account for almost every shift in the wild:

Images without dimensions

The browser does not know how big the image will be until it loads, so it reserves zero space. When the image arrives, everything below it shifts.

The fix is one line:

<img src="/cookie.jpg" alt="..." width="640" height="480" />

Or in CSS:

img { aspect-ratio: 4 / 3; height: auto; }

The browser uses width and height to compute an aspect ratio and reserves space immediately. This is a free CLS win that almost no one does.

Late loading fonts

A custom font usually has different metrics from the fallback. When it swaps in, every line of text shifts.

Mitigation:

font-display: optional to skip the swap entirely on slow connections.
size-adjust, ascent-override, descent-override in @font-face to make the fallback look like the custom font.
The next/font package and the modern Fontsource setup handle this for you.

Dynamic content (ads, embeds, banners) injected without reserved space

The fix is to always reserve the space before the content arrives. A skeleton, a placeholder div with a min height, an explicit aspect-ratio. Anything that holds the slot.

.ad-slot   { min-height: 300px; }
.embed-yt  { aspect-ratio: 16 / 9; }

If the dimensions are unknown, do not inject content above the user's viewport at all. Inject below.

Decision 5: The network is the bottleneck

A perfectly written app on a slow network is still slow. Two layers of fixes:

Compress everything

# nginx (or your CDN equivalent)
gzip on;       # compresses text by 70%+
brotli on;     # compresses 20-25% better than gzip

Most CDNs and platforms do this by default. Confirm in DevTools (Network tab, Headers, look for content-encoding). If you see text/css files at 100KB uncompressed, something is misconfigured.

Cache aggressively, invalidate precisely

Static assets (JS bundles, CSS, fonts, images) should be cached for a year, with a hash in the filename so a deploy busts the cache:

Cache-Control: public, max-age=31536000, immutable

HTML responses should be revalidated each time:

Cache-Control: no-cache

Most build tools (Vite, Next.js, Astro) handle hash naming automatically. Your CDN (Vercel, Netlify, Cloudflare) sets the headers.

For dynamic content, use stale-while-revalidate:

Cache-Control: public, max-age=60, stale-while-revalidate=600

Reads:

Trust this for 60 seconds. After that, keep serving the stale copy for up to 10 minutes while you fetch a fresh one in the background.

That single header is the secret to APIs that feel instant under load.

Use HTTP/2 or HTTP/3

If your server still answers in HTTP/1.1, you are wasting connections. Modern hosting gives you HTTP/2 or HTTP/3 (QUIC) for free. Multiplexing means dozens of small requests share a single connection, so you can stop bundling 200 modules into a single mega bundle out of fear.

Preconnect and DNS prefetch

For domains you know the page will hit (analytics, fonts, CDN, API), tell the browser early:

<link rel="preconnect" href="https://api.example.com" crossorigin />
<link rel="dns-prefetch" href="https://cdn.example.com" />

Saves 100 to 500 ms on the first request to that origin.

Decision 6: Make the rest of the page feel fast

A few moves that do not show up on Lighthouse but real users feel:

Skeletons over spinners. A grey placeholder shaped like the content feels faster than a centered spinner. The page looks alive.
Optimistic UI for mutations. When the user clicks "Like", increase the count immediately. Roll back if the request fails. (See useOptimistic in React 19.)
Prefetch on hover or intent. Next.js's <Link> does this automatically. For other apps, use fetchpriority="low" on speculative requests, or a library like Quicklink.
Defer below the fold. Anything not visible can wait. <img loading="lazy">, <iframe loading="lazy">, IntersectionObserver for components.
Avoid display: none for things you will show in 50ms. Build them off screen, animate in. The user perceives the action faster.

Decision 7: A practical performance budget

A budget is a number you commit to and let your CI enforce. Without one, performance rots over time.

A starting budget for most apps:

Asset	Budget
Main bundle JS	< 100 KB gzipped on the entry route
CSS	< 50 KB gzipped
Images on first paint	< 200 KB total
Fonts	1 to 2 weights, woff2, < 100 KB
Total page weight	< 500 KB on first paint
LCP	< 2.5 s on a slow 4G mid range phone
INP	< 200 ms
CLS	< 0.1

Plug a tool like lighthouse-ci, bundlesize, or size-limit into CI. If a PR pushes the bundle past the budget, the build fails. The PR explains itself.

Decision 8: Devtools you should know

Lighthouse panel for one-off audits.
Performance panel to record a real interaction and see where time goes. The flame graph is your best friend.
Network panel with throttling. Set "Fast 3G", reload, watch what happens.
Coverage panel to find unused JS and CSS.
WebPageTest (webpagetest.org) for a deeper, scriptable analysis. The waterfall view is iconic.
bundle-analyzer plugins for Vite, Webpack, and Next.js. See what is in your bundle, by file, sorted by size.
web-vitals extension to see real metrics in the browser bar as you click around.

A peek under the hood

What really happens between the click and the pixels:

DNS lookup for the domain.
TCP / TLS handshake with the server.
HTTP request for the HTML.
HTML streams to the browser. The parser starts immediately.
CSS in the head blocks rendering until it parses. This is why critical CSS matters.
<script> tags without defer/async block the parser. This is why script placement matters.
Layout computes the size and position of every element.
Paint fills in pixels.
Composite stacks layers and shows the final frame.
JavaScript hydrates any framework on the page, attaching event listeners.

Two practical consequences:

Anything that delays steps 4 to 8 hurts LCP. Fonts, images, render blocking CSS, server time.
Anything that runs on the main thread after step 10 hurts INP. Heavy hydration, large JS bundles, third party scripts.

That mental model is enough to debug almost any performance issue you will hit.

Tiny tips that will save you later

Test on a real low end phone. Your MacBook does not represent your users.
Throttle to slow 4G in DevTools before believing your local times.
Set width and height on every image and iframe.
Use loading="lazy" on images below the fold.
Self host fonts. Preload one. Use font-display: swap.
Code split by route.
Remove dependencies you do not use. npx depcheck finds them.
Audit third party scripts. Analytics, tag managers, chat widgets are often the slowest thing on a page.
Run Lighthouse in CI. Performance regresses silently otherwise.
Track INP in production. Most regressions live in JavaScript work, not in the network.
Cache HTML for short windows with stale-while-revalidate to absorb traffic spikes without losing freshness.

Wrapping up

So that is the whole story. We were tired of building beautiful sites that felt slow. We learned that the user only cares about three things: did the page show up, does it respond when I tap, is it staying still. Google bottled those into LCP, INP, and CLS. We measured with Lighthouse, CrUX, and web-vitals. We fixed LCP with preloading, modern image formats, server rendering, and font tactics. We fixed INP by yielding to the main thread, splitting bundles, cutting work, and moving heavy compute to workers. We fixed CLS with image dimensions, font metric overrides, and reserved space.

We taught our network to compress, cache, preconnect, and prefetch. We set a budget, plugged it into CI, and stopped letting bundle size sneak upward.

Once that map is in your head, web performance stops feeling like a dark art and starts feeling like a small set of repeatable habits. You ship fast pages on purpose, not by accident.

Happy optimizing, and may your Vitals always be green.

Learning the Web Platform APIs As If You Built Them Yourself

Mohamed Idris — Sun, 17 May 2026 13:05:00 +0000

If you have ever reached for a library to do something the browser already does, you have met the gap this post is about. Need a debounce? You wrote a useEffect. Need to detect when a card scrolls into view? You added a 300 line library. Need offline support? You shrugged and gave up.

The browser has changed. Modern browsers ship a generous, capable platform. Most of the libraries we still install in 2026 were written when the platform was missing the feature. They are not missing anymore.

A senior frontend engineer knows what the browser already gives them, and reaches for it before reaching for npm.

That is the gap this post fills.

What is the web platform, really

Think of the browser as a small operating system that runs in a tab. It has storage, a network stack, threads, scheduling, sensors, sometimes even a file system and Bluetooth. Each capability has an API. Many of them are excellent. Many of them are five lines of code instead of a 12KB dependency.

Two ideas drive the whole thing:

The platform is doing more than you think. Capabilities ship every six weeks across all the major browsers.
Promises and observers are the shape. Most modern APIs are either awaitable or "watch this thing and call me back".

That is the whole vibe.

Let's pretend we are building one

We are not building the platform. We are doing a senior level tour of it. For the running example, we will sprinkle a tiny read later notes app with native APIs as we go. Save notes offline, fetch articles, observe the page, schedule work, broadcast across tabs.

API 1: `fetch` (and AbortController), the network everyone forgets has features

Every frontend engineer knows fetch. Half of them only use 20% of it.

const res = await fetch("/api/notes", {
  method:      "POST",
  headers:     { "Content-Type": "application/json", Accept: "application/json" },
  body:        JSON.stringify({ title: "Read later" }),
  credentials: "include",        // send cookies on cross origin requests
  cache:       "no-cache",       // override default
  mode:        "cors",           // also "same-origin", "no-cors"
  signal:      ctrl.signal,      // AbortController
});

if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();

The features senior engineers actually use:

`AbortController` for cancelling

const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), 5000);   // 5s timeout

try {
  const res = await fetch(url, { signal: ctrl.signal });
} finally {
  clearTimeout(timer);
}

The same AbortController works with addEventListener, with most modern Promise APIs, and with React Query's queries. Make it your default mental model: any long lived async work should be cancellable.

The shortcut for "fetch with timeout":

fetch(url, { signal: AbortSignal.timeout(5000) });

Streaming responses

The body is a ReadableStream. You can consume it as it arrives, perfect for AI streaming or large downloads:

const res = await fetch("/api/stream");
const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log("chunk:", value);
}

`Response` and `Request` are real classes

You can build them, store them, clone them. Service Workers rely on this. The same Response API you receive from fetch is the one you return from a Service Worker.

API 2: Storage, three flavors

The browser has three storage mechanisms. Pick on purpose.

`localStorage` and `sessionStorage`

Tiny key value store. Synchronous. Strings only. Good for: small UI state (theme, last opened tab), tiny preferences. Bad for: anything large, anything secret, anything that should sync.

localStorage.setItem("theme", "dark");
localStorage.getItem("theme");
localStorage.removeItem("theme");

sessionStorage is the same, scoped to the tab. Cleared on close.

A senior level rule: never store auth tokens in localStorage. JavaScript can read it, which means every third party script can too.

Cookies

Sent automatically with every same origin request. The browser respects HttpOnly, Secure, SameSite. We covered them in the auth post. Use them for sessions and CSRF tokens.

IndexedDB, the actual database

A real client side database. Asynchronous. Stores anything structurable, including blobs. Indexed for fast queries. Quotas in the megabytes to gigabytes range.

The native API is famously verbose. Use a tiny wrapper like idb-keyval for simple cases or Dexie.js for richer querying.

import { get, set, del } from "idb-keyval";

await set("note:42", { title: "Read later", body: "..." });
const note = await get("note:42");
await del("note:42");

Use IndexedDB for: offline caches, drafts, full text search indexes, large user data, anything you need to survive a refresh and a flaky network. It is the storage that makes serious offline apps possible.

In 2026 there is also an exciting trend: SQLite in the browser, via wasm libraries like sql.js and wa-sqlite, often backed by IndexedDB or the Origin Private File System (OPFS). Real SQL queries on the client. Worth knowing about for offline first apps.

API 3: Service Workers, the engine of offline

A Service Worker is a script that runs in the background, separate from any page, and can intercept network requests for a whole origin. It is how websites become installable apps that work offline.

// app/main.ts
if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register("/sw.js");
}

// public/sw.js
self.addEventListener("install", (e) => {
  e.waitUntil(caches.open("v1").then((c) => c.addAll(["/", "/styles.css", "/app.js"])));
});

self.addEventListener("fetch", (e) => {
  e.respondWith(
    caches.match(e.request).then((cached) => cached || fetch(e.request))
  );
});

What that gives you: the page loads from cache instantly, even offline.

The senior level patterns:

Cache first for static assets that change rarely.
Network first, cache fallback for HTML.
Stale while revalidate for API responses.
Use a tool, do not hand roll. Workbox (Google) and Vite PWA Plugin scaffold a sane Service Worker in a few lines. They handle caching strategies, precaching, runtime caching, navigation fallback, and updates.

The full PWA story (offline + installable + push notifications) is a real thing in 2026. Browsers across Mac, Windows, Linux, Android, and even iOS support it. For an app that runs daily, "Add to Home Screen" is real distribution.

API 4: Web Workers, threads for compute

JavaScript runs on a single thread. Long work blocks the page. A Web Worker runs a script on a separate thread, communicating by message passing.

// worker.ts
self.onmessage = (e) => {
  const result = expensiveCompute(e.data);
  self.postMessage(result);
};

// main.ts
const worker = new Worker(new URL("./worker.ts", import.meta.url), { type: "module" });
worker.postMessage(input);
worker.onmessage = (e) => setResult(e.data);

The friendlier modern API: Comlink turns the worker into a proxy you can await:

// worker.ts
import { expose } from "comlink";

expose({
  parseMarkdown(md: string) { return slowParser(md); },
});

// main.ts
import { wrap } from "comlink";
const api = wrap<{ parseMarkdown(md: string): string }>(
  new Worker(new URL("./worker.ts", import.meta.url), { type: "module" })
);
const html = await api.parseMarkdown(text);

Use Web Workers for: heavy parsing (Markdown, syntax highlighting, JSON), image processing, data transforms, anything more than 50ms of compute. The page stays smooth, INP stays under 200ms.

A close cousin: requestIdleCallback runs a function when the browser is idle. Great for non urgent work like analytics flushing.

requestIdleCallback(() => sendQueuedAnalytics(), { timeout: 2000 });

API 5: IntersectionObserver, "tell me when this is on screen"

Before this API, "is the element visible" was solved by listening to scroll and reading layout in a tight loop. It was awful.

Now:

const obs = new IntersectionObserver((entries) => {
  for (const entry of entries) {
    if (entry.isIntersecting) {
      console.log("visible:", entry.target);
    }
  }
}, { rootMargin: "200px" });

document.querySelectorAll(".lazy").forEach((el) => obs.observe(el));

Uses for senior frontends:

Lazy load images and components before they are needed.
Infinite scroll: observe a sentinel at the bottom of the list.
Trigger animations when an element scrolls into view.
Track impressions for analytics.

rootMargin lets you start the work early, so the user never sees the loading state.

A close cousin: ResizeObserver fires when an element changes size. Great for charts, tables, and components that need to re-render on layout changes:

new ResizeObserver(([entry]) => {
  drawChart(entry.contentRect.width, entry.contentRect.height);
}).observe(chartEl);

And MutationObserver for "tell me when the DOM changed". Niche but lifesaving for browser extensions and integrations with markup you do not control.

API 6: BroadcastChannel, talking across tabs

If a user has your app open in three tabs and logs out in one, the others should know. BroadcastChannel posts messages across same origin tabs:

const ch = new BroadcastChannel("auth");
ch.postMessage({ type: "logout" });
ch.onmessage = (e) => { if (e.data.type === "logout") goToLogin(); };

Five lines, no library. Use it for: logout sync, cache invalidation across tabs, "this item just changed" notifications.

For more general cross window coordination, the Web Locks API ensures only one tab does a piece of work at a time:

await navigator.locks.request("sync-notes", async () => {
  await syncNotesWithServer();
});

Other tabs that try to acquire the lock will queue. Brilliant for "only one tab should be syncing".

API 7: Clipboard, Share, File access, the human integration layer

These are the APIs that make a web app feel native.

Clipboard

await navigator.clipboard.writeText("hello");
const text = await navigator.clipboard.readText();

Modern, async, permission gated. The old document.execCommand("copy") is deprecated. For images and other rich data, use navigator.clipboard.write with ClipboardItem.

Web Share API

if (navigator.share) {
  await navigator.share({
    title: "Mochi's Blog",
    text:  "A great post",
    url:   "https://example.com/post",
  });
}

On mobile, this opens the system share sheet. On desktop, it falls back gracefully. One line replaces a custom share modal.

File System Access

const handle = await window.showSaveFilePicker({
  suggestedName: "notes.json",
  types: [{ description: "JSON", accept: { "application/json": [".json"] } }],
});
const writable = await handle.createWritable();
await writable.write(JSON.stringify(data));
await writable.close();

Real "save as" dialog, real file. Limited to Chromium browsers in 2026 but excellent for productivity apps.

The simpler alternative for downloads is the venerable <a download>:

const url = URL.createObjectURL(new Blob([data], { type: "application/json" }));
const a = Object.assign(document.createElement("a"), { href: url, download: "notes.json" });
a.click();
URL.revokeObjectURL(url);

API 8: View Transitions, navigation feels smooth

A genuinely magical API. Animate between any two DOM states with one line.

document.startViewTransition(() => {
  // any DOM mutation here
  setTheme("dark");
});

The browser captures a snapshot before, applies your changes, captures after, and animates between them. With CSS view-transition-name on shared elements, you get FLIP-style transitions for free.

In 2026, the cross document version (@view-transition) lets multi page apps animate between full page navigations as smoothly as SPAs. This is one of the reasons SPAs are no longer the only path to good UX.

API 9: Scheduler, Idle Detection, and modern timing

The scheduler family of APIs, increasingly supported, gives you fine grained control over priority:

// new in 2024+ browsers
await scheduler.yield();        // give the browser a frame
scheduler.postTask(work, { priority: "background" });

If scheduler.yield() is not available, the polyfill is a setTimeout(0) plus a microtask check.

The classic timing tools still matter:

requestAnimationFrame for any visual update tied to the next frame. Always use it for animations driven by JS.
performance.now() for high resolution timing.
PerformanceObserver to subscribe to LCP, INP, CLS, long tasks, navigation timing, resource timing. This is what web-vitals is built on.

new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) console.log(entry);
}).observe({ entryTypes: ["longtask", "layout-shift", "largest-contentful-paint"] });

Drop into devtools when you want to see what is actually slow.

API 10: Notifications, Push, Background Sync

For "this app feels real" features:

Notifications: new Notification("Hi") with permission. Used as the visual layer for Push.
Push: a Service Worker can receive pushes from your server even when the page is closed. Requires the user to grant permission and your server to send via the Web Push protocol.
Background Sync: the browser will retry a queued task when the user comes back online. Perfect for "send this comment whenever there is connectivity".

These are senior level features. Only enable them where they pay off. Most users have notification fatigue, so ask politely or not at all.

API 11: The "knows about the user" APIs (use sparingly)

The platform has a long tail of "tell me about the device" APIs. Senior engineers know they exist and use them with care.

matchMedia("(prefers-color-scheme: dark)").matches for theme detection.
matchMedia("(prefers-reduced-motion: reduce)").matches to respect motion preferences.
navigator.connection (Network Information API) for adaptive loading. Slow 3G? Send fewer images.
document.visibilityState to pause work when the tab is hidden.
navigator.locks (already mentioned).
Battery, Bluetooth, USB, Serial, Geolocation: each is a permissioned API, useful for very specific apps.

The principle: respect the user, ask before you peek. Permission prompts kill conversion if used carelessly.

API 12: Modern selection, drag, paste, undo

A handful of small APIs that delete entire libraries:

getSelection() for the current text selection.
document.execCommand is deprecated. For rich text, use contenteditable plus a library like TipTap or Lexical.
InputEvent with inputType ("insertText", "deleteContentBackward", etc.) for fine grained input handling.
HTMLDialogElement.showModal() for native modals (we covered this in the HTML post).
<details> and <summary> for native disclosures, no JS needed.
<input type="search">, type="date", type="time", type="color" for native pickers on mobile.

A surprising amount of "I need a library for this" turns into "the browser already does it" once you check first.

API 13: WebRTC, WebSockets, SSE, beyond request/response

Three transports for real time:

WebSockets for bidirectional persistent connections. We mentioned this in the HTTP post.
Server-Sent Events (EventSource) for one way streaming from server to client. Simpler than WebSockets, plays nicely with HTTP infrastructure.
WebRTC for peer to peer audio, video, and data. The transport behind every browser based video call.

Most apps need SSE for live updates and never touch the others. Reach for them when you have a specific need (real time collaboration, video, gaming).

A peek under the hood

What really happens when you call a platform API:

JavaScript calls into the browser's C++ implementation.
The browser does the work (often on another thread or in another process).
The result comes back as a Promise resolution, an event, or a callback.
Your code runs in the JS event loop.

Two consequences for senior engineers:

Native APIs are usually faster than userland equivalents because the heavy lifting happens off the main thread.
Browser support varies. Use caniuse.com before committing. For features you must have everywhere, polyfills exist. For features that gracefully degrade, feature detect with if ("foo" in window) and ship the better experience to capable browsers.

Tiny tips that will save you later

Read MDN. It is the single best web platform documentation, and it is free.
Use caniuse.com before adopting any platform API. Browser share matters.
Feature detect, do not user agent sniff. if ("share" in navigator) is the right check.
Cancel everything. AbortController works with fetch, with addEventListener, with most modern APIs.
Use IntersectionObserver instead of scroll listeners.
Use ResizeObserver instead of window resize listeners when you only care about an element.
Use BroadcastChannel for cross tab communication.
Use idb-keyval or Dexie for IndexedDB unless you really enjoy callbacks.
Use Workbox or Vite PWA for Service Workers.
Use view-transition for navigation animations. Free polish.
Respect prefers-reduced-motion and prefers-color-scheme. They are one query away.
Keep platform APIs small. Wrap each in a tiny module so the call sites do not get noisy.

Wrapping up

So that is the whole story. The web platform stopped being a dumb document viewer years ago. Modern browsers ship a small operating system: a network stack with cancellation and streaming, three storage tiers, real threads, real schedulers, observers for everything that used to need a polling loop, broadcast channels for cross tab life, file system access, share sheets, push notifications, and beautiful view transitions.

A senior frontend engineer treats these as the first toolkit, not the last resort. The libraries on npm exist because the platform was missing the feature. Many features have shipped. Many libraries can come out of your package.json if you check what the browser already does.

Once that map is in your head, you write less code, ship smaller bundles, and build apps that feel like the device they run on.

Happy platforming, and may your dependency list stay short.

How to Actually Log Out a User When You Use JWT

Mohamed Idris — Sat, 16 May 2026 16:04:34 +0000

JWT is stateless and fast, but logout is tricky. Here is the full story with simple analogies, the jti blacklist trick, password change invalidation, refresh token rotation, and Node.js code.

The problem in one sentence

You log a user out, but their token still works until it expires. That is scary for any app that touches sensitive data.

This post walks through why that happens and how to fix it properly. I will keep it simple and use real life analogies so it sticks in your head.

This post was inspired by a great post from Mohamed Kamal in the Node.js Egypt group. He shared a solid pattern. I am going to explain the same idea slowly, then add the parts that make it production grade.

First, a mental model: the festival wristband

Imagine you go to a music festival. At the entrance they give you a wristband.

The wristband has your info printed on it: your name, your ticket type (VIP or normal), and the date it stops working.
The guard at every stage just looks at your wristband. He does not call the main office to ask "is this person still allowed in?"
That makes entry super fast. One guard can check thousands of people.

This wristband is a JWT (JSON Web Token).

The fact that the guard does not call the office is what we call stateless. The server does not keep a list of who is logged in. All the info is inside the token itself, and the signature proves it is real and was not edited.

This is great for speed and scaling. You can add 10 more servers and none of them need a shared "who is logged in" list. Any server can read the wristband and trust it.

So where is the problem?

You leave the festival early. You go home.

Your wristband is still on your wrist. It still says VIP. It still works until the festival ends.

If someone cuts it off your wrist (or you gave it to a friend), they can walk back in. The guard has no idea you "left". He only checks the wristband, and the wristband is still valid.

That is the JWT logout problem.

When a user clicks Logout, you usually just delete the token from the browser. But if a copy of that token was stolen earlier, it keeps working until the expiry time. The server never said "this token is dead now".

For a blog, who cares. For a banking app, a health app, or anything with private data, this is a real risk.

The naive fixes (and why they are not enough)

"Just make the token expire fast."
Good instinct, but if it expires every 5 minutes, the user has to log in again every 5 minutes. Annoying.

"Store every active token in the database and check it on every request."
This works, but now you call the database on every single request to ask "is this token still alive?". You just threw away the main benefit of JWT, which was being stateless and fast. At that point a normal session in the database is simpler.

So we need a middle path. We want most requests to stay fast and stateless, but we still want the power to kill a token when we need to.

The real solution, step by step

The pattern has a few moving parts. Let us build them one at a time.

Part 1: Two tokens, not one (access token + refresh token)

Stop using one long living token. Use two.

Access token

Short life. Think 5 to 15 minutes.
This is the festival wristband. The server trusts it without checking a database.
Used on every normal request (get profile, load dashboard, etc).

Refresh token

Long life. Think 7 to 30 days.
This is like your ID card kept at the front desk.
It has only one job: when your wristband expires, you show the ID card and get a fresh wristband.

Analogy: the wristband gets you into stages quickly. When it stops working after 15 minutes, you walk to the front desk, show your ID card, and they print you a new wristband. You do not need to buy a new ticket.

Why this matters for logout: because the access token only lives 15 minutes, even if logout is not perfect, a stolen access token dies on its own very soon. The damage window is tiny. The real control point becomes the refresh step.

Part 2: Give every token an ID (the `jti`)

jti means JWT ID. It is just a unique id you put inside the token when you create it. Usually a UUID.

Think of it as a serial number on the wristband.

Why do we need a serial number? Because if we ever want to ban one specific wristband, we need a way to point at it and say "that one, number 8f3a..., is banned".

const { v4: uuidv4 } = require("uuid");
const jwt = require("jsonwebtoken");

function createAccessToken(user) {
  return jwt.sign(
    {
      sub: user.id,
      role: user.role,
      jti: uuidv4(), // the serial number
    },
    process.env.ACCESS_SECRET,
    { expiresIn: "15m" }
  );
}

Part 3: The blacklist (also called a denylist)

When the user logs out, we take the token serial number (jti) and put it on a banned list.

This is exactly like the festival having a small "banned wristbands" sheet at the front desk. The guards at the stages still do not check it (they stay fast). But the front desk does check it before giving out a new wristband.

So:

Logout puts the jti on the banned list.
The refresh step (front desk) checks the banned list before giving a new access token.
If the jti is banned, refresh is refused. No new wristbands for you. And since the old access token dies in a few minutes anyway, the user is fully out very soon.

This is the key trick. We did not check the blacklist on every request. We only check it at the refresh step. So normal requests stay fast and stateless, and we still get real logout.

Note: in the original post the blacklist was checked at refresh time. That is the smart, cheap choice as long as your access token is short lived. If your access token lives for hours, that small window becomes a big risk. Keep access tokens short.

Part 4: Auto cleanup with a TTL index

A banned list that grows forever is a problem. We do not need to remember a banned token after it would have expired anyway. A dead token cannot be used, banned or not.

MongoDB has a feature called a TTL index (Time To Live). You tell Mongo "delete this document automatically after this date". Mongo does the cleanup for you.

Analogy: the front desk shreds old banned wristband notes at the end of each night. No one keeps paper forever.

const mongoose = require("mongoose");

const blacklistSchema = new mongoose.Schema({
  jti: { type: String, required: true, index: true },
  // when the original token would have expired anyway
  expiresAt: { type: Date, required: true },
});

// TTL index: Mongo deletes the row when expiresAt is reached
blacklistSchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });

module.exports = mongoose.model("BlacklistedToken", blacklistSchema);

Part 5: Kill all old tokens when the password changes

Here is a nasty case. A hacker stole a user token. The user feels something is wrong and changes the password. With plain JWT, the hacker token still works, because the token does not care about the password.

The fix is a timestamp on the user. Call it credentialsChangedAt (the original post called it changeCredentials).

The rule is simple:

If the token was created before the user last changed their password, the token is dead.

Analogy: the festival announces "we changed the wristband color to green at 2pm. Any blue wristband is now invalid." You do not need to hunt down every blue wristband one by one. One announcement kills them all at once.

// inside your auth middleware, after verifying the token signature
if (
  user.credentialsChangedAt &&
  decoded.iat * 1000 < user.credentialsChangedAt.getTime()
) {
  return res.status(401).json({ message: "Token no longer valid, please log in again" });
}

iat is "issued at", a standard field JWT puts in automatically that says when the token was created.

This one timestamp gives you a powerful "log out everywhere" button for free. Change password, all old sessions die.

Level up: refresh token rotation and theft detection

This part was not in the original post, but it is the modern best practice and it is worth knowing.

Right now our refresh token (the ID card) lives for many days. If someone steals it, they can keep getting fresh wristbands for days. Not good.

Refresh token rotation means: every time you use the refresh token to get a new access token, you also get a brand new refresh token, and the old one is thrown away. One time use only.

Analogy: every time you use your ID card at the front desk, they shred it and hand you a new ID card. The old card number is now dead.

Now the clever part, reuse detection (theft detection):

If an old, already used refresh token shows up again, that is a huge red flag. It means two people have the card: the real user and a thief. A normal user never reuses an old card, because they always have the newest one.

So when the server sees a used refresh token come back, it assumes theft and kills the entire token family for that login. Both the real user and the thief are logged out. The user logs in again, the thief is locked out.

Analogy: if security sees a shredded ID card number being used at the door, they lock the whole account and call you to confirm it is really you. Annoying for a second, much safer overall.

Quick lifetime guide that the big providers recommend:

Token	Lifetime	Why
Access token	5 to 15 minutes	Small damage window if stolen
Refresh token (sensitive apps)	7 to 30 days	Balance of safety and not annoying the user
Refresh token (single page web app)	up to 24 hours	Browsers are more exposed, keep it short

Where do you store these tokens in the browser?

This part trips up almost every junior, so read slowly.

localStorage: easy to use, but any JavaScript on your page can read it. If an attacker sneaks in a script (an XSS attack), they read your token instantly. OWASP openly says do not keep session tokens in localStorage.

httpOnly cookie: JavaScript cannot read this cookie at all. Even if an attacker runs a script on your page, they cannot read the token out of it. The trade off is you must protect against CSRF (use the SameSite cookie setting and CSRF tokens).

The recommended hybrid setup today:

Access token: keep it in memory only (a variable in your app state). It is short lived, so losing it on refresh of the page is fine, you just silently get a new one.
Refresh token: store it in a secure, httpOnly cookie. Scripts cannot touch it, and it is the long lived secret you most want to protect.

Analogy: you keep the cheap day pass (access token) in your pocket where it is easy to grab. You keep your passport (refresh token) in the hotel safe where no random person can reach it.

Putting the whole flow together

Login

Check email and password.
Create an access token (15 min) with a unique jti.
Create a refresh token (store it server side or as a signed token with its own jti).
Send the access token to be kept in memory, and the refresh token in an httpOnly cookie.

Normal request (load dashboard, etc)

Verify the access token signature. Fast. No database.
Check the credentialsChangedAt rule.
Done. This is the stateless fast path.

Access token expired

Browser calls the refresh endpoint. The httpOnly cookie is sent automatically.
Server checks: is this refresh jti on the blacklist? Was it already used (reuse detection)?
If all good, issue a new access token and a new refresh token, retire the old refresh token.

Logout

Add the refresh token jti (and optionally the current access token jti) to the blacklist with an expiresAt.
Clear the cookie.
The access token dies on its own in a few minutes. The refresh token is already banned. User is fully out.

Password change

Update credentialsChangedAt = now.
Every token created before that instant is dead everywhere, automatically.

Here is a compact logout and refresh example:

// LOGOUT
app.post("/logout", auth, async (req, res) => {
  const { jti, exp } = req.user; // from the verified token

  await BlacklistedToken.create({
    jti,
    expiresAt: new Date(exp * 1000), // matches token expiry, TTL cleans it later
  });

  res.clearCookie("refreshToken");
  res.json({ message: "Logged out" });
});

// REFRESH
app.post("/refresh", async (req, res) => {
  const token = req.cookies.refreshToken;
  if (!token) return res.status(401).json({ message: "No refresh token" });

  let decoded;
  try {
    decoded = jwt.verify(token, process.env.REFRESH_SECRET);
  } catch {
    return res.status(401).json({ message: "Invalid refresh token" });
  }

  // is this refresh token banned (logged out or reused)?
  const banned = await BlacklistedToken.findOne({ jti: decoded.jti });
  if (banned) return res.status(401).json({ message: "Token revoked" });

  const user = await User.findById(decoded.sub);
  if (!user) return res.status(401).json({ message: "User not found" });

  // password changed after this token was made? kill it
  if (
    user.credentialsChangedAt &&
    decoded.iat * 1000 < user.credentialsChangedAt.getTime()
  ) {
    return res.status(401).json({ message: "Please log in again" });
  }

  // rotation: ban the old refresh token, issue fresh ones
  await BlacklistedToken.create({
    jti: decoded.jti,
    expiresAt: new Date(decoded.exp * 1000),
  });

  const newAccess = createAccessToken(user);
  const newRefresh = createRefreshToken(user); // new jti inside

  res.cookie("refreshToken", newRefresh, {
    httpOnly: true,
    secure: true,
    sameSite: "strict",
  });
  res.json({ accessToken: newAccess });
});

A note on MongoDB vs Redis for the blacklist

The original post used MongoDB with a TTL index, and that is perfectly fine and clean. Many teams use Redis instead because it is an in memory store built for exactly this kind of fast key lookup, and it also supports automatic expiry. If your blacklist gets very hot (checked a lot), Redis is the common choice. If you are early or your traffic is normal, MongoDB with a TTL index is a solid, simple start. Do not over engineer too early.

Common mistakes juniors make

Using one long lived token for everything. Always split into short access and longer refresh.
Forgetting to revoke the refresh token on logout. If you only handle the access token, the refresh token can still mint new ones. Logout must kill the refresh token.
Checking the blacklist on every single request. That kills the stateless speed benefit. Check it at the refresh step and keep access tokens short.
Storing tokens in localStorage because the tutorial did. Prefer memory for access and httpOnly cookie for refresh.
No credentialsChangedAt. Without it, changing the password does not actually protect a user whose token was already stolen.
Letting the blacklist grow forever. Always set a TTL so dead entries clean themselves up.

The one paragraph summary

JWT is fast because the server trusts the token without a database lookup, like a guard glancing at a wristband. The cost of that speed is that logout does not naturally kill a token. You fix it by using a short lived access token plus a longer refresh token, giving every token a unique jti serial number, putting that jti on a blacklist at logout and checking the blacklist only at the refresh step, auto cleaning the blacklist with a TTL index, and adding a credentialsChangedAt timestamp so a password change kills all old tokens at once. Add refresh token rotation with reuse detection and store tokens safely (access in memory, refresh in an httpOnly cookie) and you have a real, production grade auth system.

Authentication is not just login and register. The small security details are what separate a toy project from a real system.

Sources and further reading

Big thanks to Mohamed Kamal for the original post in Node.js Egypt that started this. If this helped you, share it with a junior who is still using one giant token for everything.

Learning HTTP, APIs, and Auth As If You Built It Yourself

Mohamed Idris — Sat, 16 May 2026 13:05:00 +0000

If you have ever built a frontend that calls a backend, you have run into all three of these. You wrote a fetch. You picked a URL shape. You stuck a token somewhere and prayed. Something returned a 200 with { ok: false } in the body, and you spent the afternoon arguing in the team chat about whether that was correct.

It probably was not.

There is a small set of conventions that the whole web agreed on, decades ago, and most apps half know them. Frontend engineers who fully know them ship cleaner, more debuggable systems and have shorter Slack arguments.

That is the gap this post fills.

What are HTTP, APIs, and auth, really

Think of the web as a polite postal system. Your client (the browser) writes a letter (a request), the server reads it, writes back (a response), and the conversation ends. Each letter has an envelope (headers), a way of being addressed (the URL), and a body (the data). Each reply has a stamp on the front (a status code) that tells you, at a glance, what happened.

HTTP is the postal protocol itself. Verbs, headers, status codes, caching rules.
APIs are the postal addresses your team agreed on. Which URLs do what, what each one expects in the body, what it sends back.
Auth is the picture ID you put in the envelope. Who are you, and are you allowed to ask for this?

A senior frontend engineer treats those three as one fluent topic, not three separate puzzles.

That is the whole vibe.

Let's pretend we are building one

We want to design a small backend a frontend can talk to without surprises, with proper status codes, predictable URLs, and authenticated calls. We will not hand build a server. We will agree on the conventions and use any framework that respects them.

For the running example, we are designing the Mochi Recipes API: list recipes, read one, create one, log in, save a favorite. Small, but it lets us touch every important corner.

Decision 1: HTTP, the verbs and the rules

Every request is one verb plus one URL. The verbs:

GET: read. Safe (no side effects). Idempotent (same request, same result).
POST: create or trigger an action. Not idempotent.
PUT: replace the resource entirely. Idempotent.
PATCH: change part of the resource. Idempotent in spirit.
DELETE: delete. Idempotent.
HEAD: like GET but only the headers come back.
OPTIONS: what verbs and headers are allowed here? (Used for CORS preflights.)

Two things every senior should know cold:

GET must never modify state. Browsers, proxies, and prefetchers send GETs whenever they like. A GET /unsubscribe?id=42 link will be deleted by Outlook's URL preview. (Yes, this is a real bug that has happened many times.)
PUT vs PATCH: PUT /recipes/42 with a partial body replaces the recipe with that partial body and removes the missing fields. PATCH /recipes/42 with the same body changes only what was sent. Pick on purpose.

Decision 2: Status codes that say what happened

The first three letters of the response. Memorize the pattern:

2xx success
- 200 OK: the default success.
- 201 Created: after a successful POST that created a thing. Include a Location: header pointing at the new resource.
- 204 No Content: success but nothing to return. Common after DELETE.
3xx redirection
- 301 Moved Permanently: the URL changed forever. Browsers cache this.
- 302 Found, 307 Temporary Redirect: the resource is over there, for now.
- 304 Not Modified: the cached copy is still good. The body is empty.
4xx the client made a mistake
- 400 Bad Request: malformed input.
- 401 Unauthorized: you are not logged in. (Misnamed, it is really "unauthenticated".)
- 403 Forbidden: you are logged in, but not allowed.
- 404 Not Found: no such resource.
- 405 Method Not Allowed: wrong verb for this URL.
- 409 Conflict: your write would conflict with the current state (e.g. duplicate email).
- 422 Unprocessable Entity: well formed but invalid (e.g. validation errors).
- 429 Too Many Requests: slow down. Pair with Retry-After.
5xx the server made a mistake
- 500 Internal Server Error: something blew up.
- 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout: upstream issues.

The two anti patterns I see most often on real teams:

Returning 200 { ok: false } for errors. This breaks every standard tool. Use the right status code. Tools, logs, monitoring, CDNs, and the browser DevTools all rely on it.
Returning 400 for "not found". A missing user is 404, not 400. A malformed JSON body is 400. Tell them apart.

Decision 3: REST URL design

A URL points at a resource (a thing). The verb says what you are doing to it. Resources are nouns, plural, lowercase.

GET    /recipes              -> list
GET    /recipes/42           -> read one
POST   /recipes              -> create
PATCH  /recipes/42           -> update
DELETE /recipes/42           -> delete

GET    /recipes/42/comments  -> list comments on recipe 42
POST   /recipes/42/comments  -> add a comment

A few senior level rules:

Nouns, not verbs. POST /createRecipe is wrong. POST /recipes is right.
Plural, consistently. GET /recipes, not GET /recipe.
Use query parameters for filtering, sorting, paging. GET /recipes?tag=dessert&sort=-createdAt&page=2&limit=20.
Use sub paths for relationships. GET /users/42/recipes reads better than GET /recipes?userId=42 for natural ownership.
Version the API in the URL or in a header. /v1/recipes or Accept: application/vnd.example.v1+json. Pick one and never argue again.
Return JSON in a stable shape. Never change a field type or remove a key without a version bump.

If REST does not fit your needs (lots of nested data, lots of round trips), look at GraphQL or tRPC. Both are excellent in 2026. Neither replaces REST for public APIs.

Decision 4: Headers, the metadata you cannot ignore

Headers are the envelope of every request and response. The ones every senior should recognize:

Content negotiation

Content-Type:    application/json
Accept:          application/json
Accept-Language: en-US,en;q=0.9

Always set Content-Type on requests with a body. Always read it on responses (the body might not be JSON).

Auth

Authorization: Bearer <token>
Cookie:        session=...

We will dig into these in a moment.

Caching

Cache-Control: public, max-age=60, stale-while-revalidate=600
ETag:          "v3-abc123"
Last-Modified: Wed, 09 May 2026 10:00:00 GMT

The single most underused tool in frontend performance is conditional requests. A client with an ETag can ask "is this still fresh?":

GET /recipes/42
If-None-Match: "v3-abc123"

If yes, the server replies 304 Not Modified with no body. Bandwidth saved, page faster.

CORS

Access-Control-Allow-Origin:      https://app.example.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods:     GET, POST, PATCH, DELETE
Access-Control-Allow-Headers:     Authorization, Content-Type

CORS lives entirely on the server. It tells the browser which origins are allowed to call this API from JavaScript. It does not exist for security against attackers (curl ignores it). It exists to protect users from a malicious page calling another origin from their browser.

The two CORS bugs every frontend developer hits:

The preflight OPTIONS request. Before a "non simple" request, the browser sends an OPTIONS to ask permission. Your server must respond with the right headers. Most frameworks have a one-line cors middleware.
* and credentials do not mix. If your server returns Access-Control-Allow-Origin: *, the browser will refuse to send cookies. For credentialed requests, set the exact origin.

Rate limiting

X-RateLimit-Limit:     100
X-RateLimit-Remaining: 23
X-RateLimit-Reset:     1715251200
Retry-After:           60

A polite API tells the client when to back off. A polite client respects it.

Decision 5: Errors that the client can actually handle

The body of a 4xx or 5xx response should follow a stable shape. The de facto standard is RFC 7807 / 9457 Problem Details:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type":     "https://example.com/problems/validation",
  "title":    "Invalid input",
  "status":   422,
  "detail":   "Some fields failed validation.",
  "instance": "/recipes",
  "errors": [
    { "field": "title", "code": "too_short" },
    { "field": "prepMinutes", "code": "must_be_positive" }
  ]
}

A few rules:

Use the right status code first. The body explains, the status decides.
Include a stable error code per problem. UI code can switch on it without parsing English.
Include enough info to render a good error message without leaking internals.
Never echo user input back in HTML errors unless you escape it. That is a classic XSS path.

Decision 6: Authentication, the choices that actually exist

Auth is two words pretending to be one:

Authentication (authn): who are you?
Authorization (authz): what are you allowed to do?

The four mainstream patterns in 2026:

1. Session cookies (the original, still excellent)

The server creates a session, stores it server side (in a database or Redis), and sets a cookie. The browser sends the cookie automatically on every request to the origin. The server looks up the session and knows who you are.

Set-Cookie: session=opaque_id; HttpOnly; Secure; SameSite=Lax; Path=/

Every flag matters:

HttpOnly: JavaScript cannot read it. Stops XSS from stealing the token.
Secure: only sent over HTTPS.
SameSite=Lax (or Strict): only sent for same site requests, blocking most CSRF.
Path=/: sent on every path under the origin.

The security defaults are excellent. The state lives on the server where you can revoke it instantly. Best for first party web apps where the API and the frontend share an origin.

The one CSRF caveat: if you use cookies, every state changing endpoint should require either SameSite=Strict, a CSRF token, or a custom header that browsers will not send cross origin without permission.

2. JWT (JSON Web Tokens)

A JWT is a self contained token that is signed by the server. It contains the user id, expiration, and any claims you want, all readable by anyone (it is base64 encoded JSON). Only the signature can be checked by the server.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...

Pros: stateless, easy to verify on any service that has the public key, popular in SPAs, mobile, and microservices.

Cons: hard to revoke before expiration (you would need a blocklist, defeating the stateless point). Often misused to store sensitive data in the token (the body is readable by the client).

The 2026 advice:

Short lived access token (15 minutes) plus a long lived refresh token. When the access token expires, the client uses the refresh token to get a new one.
Store tokens in HttpOnly cookies, not in localStorage. Tokens in localStorage are XSS's lunch.
Never use JWTs as session cookies on a single origin web app. Use real session cookies. JWTs shine for cross origin or service to service.

3. OAuth 2.0 / OAuth 2.1

OAuth is not a login method. It is a protocol for your app to act on behalf of a user at another service. "Sign in with Google" is OAuth.

The flow you actually need to know:

Your app sends the user to Google's /authorize URL.
The user logs in to Google and clicks "Allow".
Google redirects back to your app with an authorization code.
Your server exchanges the code for an access token (and a refresh token) at Google's /token endpoint.
Your server uses the access token to call Google's APIs.

OAuth 2.1 (the modern consolidation) makes a few things mandatory:

PKCE for all authorization code flows. A short random secret the client generates and proves possession of. Closes a class of attacks.
No more Implicit grant. It was insecure in browsers. Use authorization code with PKCE.
No more Resource Owner Password grant. Bad pattern, gone.
Exact redirect URI matching. No fuzzy patterns.

For most frontend developers, you will not implement OAuth. You will use a library or a service: Auth.js / NextAuth, Clerk, Auth0, WorkOS, Stack Auth. Pick one, follow its setup, get on with your day.

4. API keys

A long opaque string a service gives a developer for server to server access. Useful for partners and CLI tools. Never put one in frontend code, ever. If a key shows up in your client bundle, it is leaked.

Decision 7: Storing tokens in the browser, the only sane way

The single most common security mistake in frontend code is putting an auth token where JavaScript can read it.

// don't
localStorage.setItem("token", token);

// don't
document.cookie = `token=${token}`;

If any third party script (analytics, chat widget, ad SDK) is XSS'd, your token leaks to it.

The right pattern:

The server sets an HttpOnly cookie with the session or refresh token.
JavaScript never sees it.
The browser sends it automatically on calls to your API.
For cross origin frontends, set the API on a subdomain and use SameSite=None; Secure cookies, with explicit CORS allowing credentials.

Modern auth libraries default to this. If yours does not, find one that does.

Decision 8: Calling APIs from the frontend without pain

Once the conventions are set, the client side patterns are simple.

`fetch`, the modern default

async function getRecipes() {
  const res = await fetch("/api/recipes", {
    headers: { Accept: "application/json" },
  });

  if (!res.ok) {
    throw new ApiError(await res.json(), res.status);
  }

  return res.json() as Promise<Recipe[]>;
}

A few habits to internalize:

fetch does not throw on 4xx or 5xx. You have to check res.ok yourself.
Always cancel in flight requests when the user navigates away or types again. AbortController is the answer:

const ctrl = new AbortController();
fetch("/api/search?q=" + q, { signal: ctrl.signal });
// later: ctrl.abort();

Wrap in a typed client. Hand rolling fetch with try/catch in 80 places is painful. Use TanStack Query for caching and retries, or tRPC, or Hey API generated clients from an OpenAPI spec, or ts-rest for typed contracts.
Use credentials: "include" when you need cookies on cross origin requests, alongside the right CORS headers.

TanStack Query, the go to data layer

import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";

function useRecipes() {
  return useQuery({
    queryKey: ["recipes"],
    queryFn: () => fetch("/api/recipes").then((r) => r.json()),
    staleTime: 60_000,
  });
}

function useCreateRecipe() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (data: NewRecipe) =>
      fetch("/api/recipes", { method: "POST", body: JSON.stringify(data) }),
    onSuccess: () => qc.invalidateQueries({ queryKey: ["recipes"] }),
  });
}

Caching, deduping, retries, background refetching, optimistic updates, all included. We have already discussed why server data does not belong in Zustand or Redux.

Decision 9: WebSockets and Server-Sent Events

For real time data (chat, notifications, live dashboards), HTTP request/response is not enough. Two real options:

Server-Sent Events (SSE): a one way stream from server to client over HTTP. Simple. Built into the browser via EventSource. Great for live updates that flow one direction.
WebSockets: a two way persistent connection. Use when both ends need to push. Heavier, more work to deploy. The browser API is WebSocket. Frameworks like Socket.IO and partykit make it friendlier.

Pick SSE first. It is simpler, plays better with HTTP infrastructure (load balancers, proxies, CDNs), and covers most "live updates" needs.

Decision 10: Senior level moves and pitfalls

A short list that separates "calls APIs" from "designs and consumes APIs well":

Always use HTTPS. Even in development, with a self signed cert if you have to. Cookies and tokens get weird without it.
Validate every input on the server. The client is not in your control. Use Zod (or your language equivalent) at the boundary.
Never trust the client about auth. Authorization happens on the server.
Pagination by default. Any list endpoint that can return more than a few hundred rows must paginate. ?page=2&limit=20 or cursor based (?after=cursor).
Rate limit even your internal APIs. A bug on the client side that hammers your endpoint will eat your database otherwise.
Set up CORS once, in middleware, not per route.
Send a Content-Length and a real Content-Type.
Use application/json for JSON, not text/json.
Use ISO 8601 timestamps with timezone. 2026-05-09T10:00:00Z. No "May 9 2026". No 1715251200000 unless you also tell the consumer it is millis.
Money in integer cents. Same lesson as the SQL post.
Document with OpenAPI or a similar spec. Future you, your other team, your AI tools, and your client generators all benefit.
Treat 5xx as your fault, 4xx as the client's. Logging, alerts, dashboards must respect that line.
Rate limit responses include the limit headers. Do not make clients guess.
For long jobs, return 202 Accepted with a polling URL, or use a webhook, or stream progress with SSE. Do not hold an HTTP request open for 30 minutes.

A peek under the hood

What really happens when your frontend calls /api/recipes:

The browser builds a request: method, URL, headers, optional body.
If cross origin and "non simple", the browser sends an OPTIONS preflight first.
DNS resolves, TCP and TLS handshake (kept warm if possible).
The request is sent over HTTP/2 or HTTP/3, multiplexed with other requests on the same connection.
The server matches the route, runs middleware (auth, rate limit, validation), runs the handler, builds a response.
The response status, headers, and body stream back.
The browser respects Cache-Control, sets cookies (Set-Cookie), updates its CORS state.
Your fetch resolves. Your app gets the parsed JSON.

That whole loop is what every "an API call" really is. Once you can picture it, debugging gets ten times faster, because you know where to look.

Tiny tips that will save you later

Use the right verb and the right status code. Half of all API arguments end here.
Set Cache-Control on every response. Even no-cache is better than nothing.
Use ETags for read heavy endpoints. Free 304s.
Always AbortController in flight requests. Especially in search-as-you-type.
Cookies for first party web apps. JWT for cross origin or services.
Never put tokens in localStorage.
Validate every body server side with Zod.
Use TanStack Query (or equivalent) for any non trivial frontend.
Page everything. Sort consistently. Paginate with stable cursors when ordering matters.
Document your API. The OpenAPI spec pays for itself.
Read RFCs once. Especially RFC 7231 (HTTP semantics), RFC 6750 (Bearer), and RFC 9457 (Problem Details).

Wrapping up

So that is the whole story. The web runs on a polite postal protocol where the verbs and the stamps already mean something specific. APIs are agreements about which addresses do what. Auth is the picture ID in your envelope.

We learned to use the right verbs (GET is safe, POST creates, PATCH updates, DELETE deletes), the right status codes (2xx success, 4xx your fault, 5xx mine), the right URL shapes (nouns, plural, sub paths for ownership), the right headers (Content-Type, Accept, Authorization, Cache-Control, ETag, CORS), and the right errors (Problem Details, stable codes, useful messages).

We picked auth on purpose: session cookies for first party web apps, JWT in HttpOnly cookies for cross origin SPAs, OAuth 2.1 for "sign in with X", API keys never in the browser. We aborted in-flight requests, cached on purpose, paginated everything, and treated client validation as cosmetic and server validation as security.

Once that map is in your head, every API conversation becomes shorter. You stop arguing about whether something should return 200 { ok: false } because you already know the answer. You stop chasing CORS ghosts because you can read the preflight in DevTools. You stop leaking tokens because you never put them where JavaScript could see them in the first place.

Happy networking, and may your 2xx always outnumber your 5xx.

Learning Next.js As If You Built It Yourself

Mohamed Idris — Fri, 15 May 2026 13:03:00 +0000

If you have ever built a React app with plain Vite, you remember the moment. Three months in, you have hand rolled a router. You have hand rolled the loading spinner pattern. You have hand rolled metadata for SEO. You have an Express server next to it for the API, and you spend half your time keeping the two in sync. Deploying is a checklist. Production caching is a guess.

You did not want to build a framework. You just wanted to ship a website.

That is the gap Next.js fills.

What is Next.js, really

Think of Next.js as a React framework with the boring parts already done. Routing, data fetching, server side rendering, caching, image optimization, fonts, head tags, deployment, all of it. You write the components, Next.js wires the rest into a coherent app that runs on the server, the edge, and the browser.

Two ideas drive the whole thing:

Server first. Pages render on the server by default. Only the parts that truly need interactivity ship JavaScript to the browser. Smaller bundles, faster first paint, better SEO, secrets stay safe.
The file system is your routing config. A folder is a route. A page.tsx inside it is the screen. A layout.tsx is the shared shell. No router config file to maintain.

That is the whole vibe.

Let's pretend we are building one

We want a React framework that handles routing, server rendering, mutations, and caching by default. We will call it Next.js.

For the running example, we are building Mochi's Blog: posts, a single post page, an author dashboard, and a comment form.

Decision 1: The folder is the route

Next.js (App Router) maps your app/ folder onto URLs.

app/
  layout.tsx              -> shared shell for the whole site
  page.tsx                -> /
  about/
    page.tsx              -> /about
  posts/
    page.tsx              -> /posts
    [slug]/
      page.tsx            -> /posts/anything
  dashboard/
    layout.tsx            -> shared shell only for /dashboard/*
    page.tsx              -> /dashboard
    settings/
      page.tsx            -> /dashboard/settings
  api/
    subscribe/
      route.ts            -> POST/GET /api/subscribe

A few rules that explain the rest of the framework:

page.tsx is a page. It receives params and searchParams props.
layout.tsx is a shell that wraps every page below it in the tree. Layouts compose: every nested layout wraps inside the parent's.
[slug] is a dynamic segment. The folder name with brackets becomes a route param.
route.ts is a backend endpoint. Export GET, POST, PUT, DELETE functions and they become handlers.
loading.tsx is the suspense fallback for that segment. Streamed in automatically.
error.tsx is the error boundary for that segment.
not-found.tsx is shown when notFound() is thrown.

A minimal layout and home page:

// app/layout.tsx
export const metadata = { title: "Mochi's Blog", description: "Cats and code." };

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <header><a href="/">Mochi's Blog</a></header>
        <main>{children}</main>
      </body>
    </html>
  );
}

// app/page.tsx
export default function HomePage() {
  return <h1>Welcome to Mochi's Blog</h1>;
}

That is a working Next.js app.

Decision 2: Server Components by default

Every component you write is a Server Component unless you opt out. Server Components run on the server, can read from a database directly, can use secrets, and ship zero JavaScript to the browser.

// app/posts/page.tsx
import { db } from "@/lib/db";

export default async function PostsPage() {
  const posts = await db.post.findMany({ orderBy: { createdAt: "desc" } });

  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}><a href={`/posts/${p.slug}`}>{p.title}</a></li>
      ))}
    </ul>
  );
}

That is the whole page. Async function, awaits the database, returns JSX. No useEffect, no loading state, no API route in between.

When you do need interactivity (state, effects, event handlers, browser APIs), opt into Client Components with "use client" at the top of the file:

// app/posts/[slug]/like-button.tsx
"use client";

import { useState } from "react";

export function LikeButton({ initial }: { initial: number }) {
  const [count, setCount] = useState(initial);
  return <button onClick={() => setCount(count + 1)}>♥ {count}</button>;
}

The mental model: default to Server Components. Reach for "use client" only on the interactive island. The pattern is server pages with small client islands inside, not whole client trees with little server islands.

Decision 3: Server Actions for mutations

When you need to write data, you do not have to hand build an API route. Write an async function with "use server" and call it from a form or a button.

// app/posts/[slug]/comment-form.tsx
import { addComment } from "./actions";

export function CommentForm({ postId }: { postId: string }) {
  return (
    <form action={addComment}>
      <input type="hidden" name="postId" value={postId} />
      <textarea name="body" required />
      <button>Post comment</button>
    </form>
  );
}

// app/posts/[slug]/actions.ts
"use server";
import { db } from "@/lib/db";
import { revalidatePath } from "next/cache";

export async function addComment(formData: FormData) {
  const postId = String(formData.get("postId"));
  const body   = String(formData.get("body"));

  await db.comment.create({ data: { postId, body } });
  revalidatePath(`/posts/${postId}`);
}

That is a full mutation. No API route. No fetch. The browser submits the form, Next.js calls the server function, the server runs it, the page revalidates, and the new comment appears.

For a richer client experience (pending state, error message, optimistic UI), pair the action with React 19's useActionState and useOptimistic hooks. Same patterns you already know, no Next.js specific magic needed.

Decision 4: Three rendering modes, one mental model

Every route picks one of three behaviors:

Static: built once at deploy time, cached forever, fastest possible. Default for routes with no dynamic data.
Dynamic: rendered on every request, can use cookies, headers, and search params freely.
Streaming: starts sending HTML immediately and fills in slow parts as data arrives. Pairs with <Suspense> and loading.tsx.

You rarely pick these explicitly. Next.js infers from what your code does. If you read cookies() or headers(), the route becomes dynamic. If you wrap a slow component in <Suspense>, that part streams.

For data that should not be revalidated on every request, you cache and tag it:

import { unstable_cache } from "next/cache";

export const getPostBySlug = unstable_cache(
  async (slug: string) => db.post.findUnique({ where: { slug } }),
  ["post-by-slug"],
  { revalidate: 60, tags: ["posts"] }
);

When you mutate, you invalidate by tag or by path:

import { revalidateTag, revalidatePath } from "next/cache";

revalidateTag("posts");          // any cache tagged "posts" is dropped
revalidatePath("/posts");        // re-render that path on next request

In Next.js 15, the modern surface for this is the use cache directive at the top of a function or component, plus cacheTag() and cacheLife() to control freshness:

"use cache";
import { cacheTag, cacheLife } from "next/cache";

export async function getRecentPosts() {
  cacheTag("posts");
  cacheLife("hours");
  return db.post.findMany({ orderBy: { createdAt: "desc" }, take: 10 });
}

The mental model: cache everything you can, tag what you cache, invalidate by tag when you mutate.

Decision 5: Route handlers for the rest

If your client (a mobile app, a third party webhook, an external integration) needs a real REST endpoint, write a route.ts:

// app/api/posts/route.ts
import { db } from "@/lib/db";
import { NextResponse } from "next/server";

export async function GET() {
  const posts = await db.post.findMany();
  return NextResponse.json(posts);
}

export async function POST(req: Request) {
  const body = await req.json();
  const post = await db.post.create({ data: body });
  return NextResponse.json(post, { status: 201 });
}

Same file system pattern, same colocation. Use Server Actions for app-internal mutations and route handlers for public APIs.

Decision 6: Navigation and links

The <Link> component from next/link does client side navigation, prefetches in view links, and keeps your layouts mounted across navigations.

import Link from "next/link";

<Link href="/posts/mochi-stole-socks">Read post</Link>
<Link href={`/posts/${slug}`} prefetch={false}>Read</Link>

For programmatic navigation, use useRouter() from next/navigation (the new App Router version, not the old next/router).

Decision 7: Images, fonts, and metadata, the boring wins

Next.js has built in components for the things every website gets wrong.

import Image from "next/image";
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

export default function Hero() {
  return (
    <div className={inter.className}>
      <Image
        src="/mochi.jpg"
        alt="A small white cat with big eyes"
        width={1200}
        height={800}
        priority
      />
    </div>
  );
}

What that gives you for free: responsive images with srcset, modern formats (AVIF, WebP), lazy loading by default, layout shift prevention, font self hosting with no FOUT, font subsetting.

For SEO, set metadata on each route:

export const metadata = {
  title: "Why my cat steals socks",
  description: "A short investigation.",
  openGraph: { images: ["/cover.png"] },
};

Or generate it dynamically:

export async function generateMetadata({ params }) {
  const post = await getPost(params.slug);
  return { title: post.title, description: post.excerpt };
}

These small wins (<Image>, next/font, metadata API) are why most production React apps run on Next.js even when they technically could ship as a Vite SPA.

Decision 8: Middleware and edge

Code that runs on every request, before any route, lives in middleware.ts at the root:

// middleware.ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  const session = req.cookies.get("session")?.value;
  const isAuthed = Boolean(session);

  if (req.nextUrl.pathname.startsWith("/dashboard") && !isAuthed) {
    return NextResponse.redirect(new URL("/login", req.url));
  }
}

export const config = { matcher: ["/dashboard/:path*", "/api/admin/:path*"] };

Middleware runs on the edge by default, so it is fast and globally distributed. Use it for authentication gates, redirects, A/B test bucketing, locale negotiation, bot blocking. Keep it light. It runs on every matched request.

Decision 9: Project structure that scales

A pattern most senior teams settle on:

app/
  (marketing)/          -> route group, does not appear in URLs
    page.tsx            -> /
    pricing/page.tsx    -> /pricing
  (dashboard)/
    layout.tsx          -> auth-protected layout
    dashboard/page.tsx  -> /dashboard
  api/
  layout.tsx
components/
  ui/                   -> design system primitives (Button, Card, Dialog)
  posts/                -> feature components
lib/
  db.ts                 -> database client
  auth.ts               -> auth helpers
  validators/           -> Zod schemas, shared between client and server

The senior level habits:

Group routes with (name)/ for sectioning without affecting URLs.
Keep server only code in lib/ and never import it from a "use client" file. (Add import "server-only" at the top of files that should never reach the browser.)
One feature, one folder. A posts feature has its server queries, components, and forms colocated.
Use the official next.config minimum. Resist the urge to customize Webpack until you must.

Decision 10: Auth, the modern story

Next.js does not ship auth, on purpose. The two clean choices in 2026:

Auth.js (formerly NextAuth): full featured, supports OAuth providers, email magic links, credentials. Sets a session cookie. Read sessions from Server Components with auth().
Clerk / Kinde / Stack Auth / WorkOS: hosted auth services with React components and a back end you do not run. Trade some money for zero auth code.
Roll your own session cookie + a strong library like iron-session or lucia-auth. Reasonable for small projects.

Whatever you pick, the rule is the same: read the session in middleware or in a Server Component, never trust client side flags. Server Components are where authorization decisions belong.

Decision 11: Deployment and runtime

The simplest deploy: push to a Git repo connected to Vercel. Build, deploy, edge middleware, image optimization, all included. That is the path the framework was designed for.

You can also self host:

next build
next start

That gives you a Node.js server. For containerized deploys, the output: "standalone" config produces a minimal output that runs anywhere Node runs.

Two runtime knobs to know:

Node.js runtime (default): full Node APIs, larger cold start, runs anywhere.
Edge runtime: a subset of APIs, V8 isolate based, low latency cold start, geographically distributed. Set per route with export const runtime = "edge";. Great for middleware and small API handlers.

A peek under the hood

What really happens when a user opens your Next.js app:

The request hits the edge or your Node server.
Middleware runs, possibly redirecting or rewriting.
Next.js matches the URL to a page.tsx plus its parent layouts.
Server Components render on the server, fetching data, awaiting promises.
The HTML streams to the browser, with <Suspense> boundaries filling in as data arrives.
A small JavaScript payload hydrates the Client Components only.
The browser shows pixels almost immediately, interactivity follows shortly after.
Subsequent navigations are client side, prefetched, and reuse the layout tree.

Two senior level consequences:

Less JS in the browser is the headline win. A typical Next.js page ships a fraction of what a typical Vite SPA ships, because Server Components stay on the server.
Caching is the second big win, and the most confusing one. Next.js caches at the data level (fetch, unstable_cache, use cache) and the route level. Get comfortable with revalidateTag and revalidatePath early.

Tiny tips that will save you later

Default to Server Components. Add "use client" only where you must.
Use <Image>, next/font, and the metadata API. Free Lighthouse points.
Use <Link> for internal navigation. Native <a> reloads the page.
Tag your caches. It pays off the first time you ship a "show fresh data" feature.
Keep secrets server side. A process.env.SECRET accessed from a "use client" file is shipped to the browser.
Use Zod schemas in lib/validators/ to share types between client forms and server actions.
Read sessions on the server. Auth checks in client code are cosmetic, not security.
Run next build in CI. Type errors and config issues show up there, not in dev.
Profile with the Vercel Analytics or next/web-vitals to track real user metrics.

Wrapping up

So that is the whole story. We were tired of stitching React, a router, an API server, an image pipeline, and a deployment script together by hand. We built a framework that does it all by default. The file system is the router. Server Components do data fetching. Server Actions do mutations. Caching is built in, with tag based invalidation. Images, fonts, and metadata are first class. Middleware runs on the edge.

We learned to default to the server, ship small client islands, cache aggressively, invalidate precisely, and let Next.js handle the boring parts so we can focus on the actual app.

Once that map is in your head, every modern React project starts to feel familiar. Next.js stops feeling like "React with extra steps" and starts feeling like the full stack toolkit you wished you had three years ago.

Happy shipping, and may your LCP always be green.

Forem: Mohamed Idris

For ambitious devs who also feel tired

What it does

Why I built it this way

Who it is for

Want to join?

Learning NestJS As If You Built It Yourself

What is NestJS, really

Let's pretend we are building one

Decision 1: Code should be organized in feature boxes

Decision 2: HTTP stuff lives in a controller

Decision 3: The brain lives in a service

Decision 4: Don't new your stuff, ask for it

Decision 5: Validate at the door with DTOs

Decision 6: Plug in extra logic with a tiny pipeline

Decision 7: Make it fast and easy to start

A peek under the hood

Tiny tips that will save you later

Wrapping up

Learning Express.js As If You Built It Yourself

What is Express, really

Let's pretend we are building one

Decision 1: Hello world in five lines

Decision 2: Routes, the verbs and the paths

Decision 3: Middleware, the soul of Express

Decision 4: Built in body parsers (no more body-parser)

Decision 5: Routers for modular structure

Decision 6: Async handlers (the Express 5 superpower)

Decision 7: Error handling middleware, the four argument signature

Decision 8: Validate every input with Zod

Decision 9: Auth, the modern Node story

Decision 10: Security middleware that should be on by default

Decision 11: TypeScript with Express, the friendly way

Decision 12: Testing Express handlers

Supertest, the classic

Real HTTP for integration tests

Decision 13: Graceful shutdown and observability

Decision 14: When to pick Express, when to pick something else

A peek under the hood

Tiny tips that will save you later

Wrapping up

Learning Prisma As If You Built It Yourself

What is an ORM, really

Let's pretend we are building one

Decision 1: We need a map of the database

Decision 2: Turn the schema into actual code

Decision 3: Every call starts with prisma

Decision 4: After prisma., you name the table

Decision 5: After the model, you pick a command

Decision 6: Inside the command, you describe what you want

Creating a user

Finding a user

Updating

Deleting

Decision 7: Joining tables with include

Decision 8: Migrations are part of the story

A peek under the hood

Tiny tips that will save you later

Wrapping up

Learning MongoDB As If You Built It Yourself

What is MongoDB, really

Let's pretend we are building one

Decision 1: The unit of data is a document, not a row

Decision 2: Four verbs, just like SQL

Insert

Find (the workhorse)

Update

Delete

Decision 3: Query operators, the dollar sign menu

Decision 4: Schema design, the part that actually matters

Embed when data is owned and read together

Reference when data is shared or grows without bound

The rule of thumb

Decision 5: Validate at the door anyway

Decision 6: Indexes work just like SQL, but read the rules

Decision 7: The aggregation pipeline, the real power tool

Decision 8: Transactions, when you really need them

Decision 9: Scaling, replication, and sharding

Decision 10: The modern stack

Decision 11: Pitfalls you only learn the hard way

Decision 4: Don't `new` your stuff, ask for it

Decision 3: Every call starts with `prisma`

Decision 4: After `prisma.`, you name the table

Decision 7: Joining tables with `include`

Self host fonts and use `font-display: swap`