DEV Community: Mohamed Idris

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.

Learning React As If You Built It Yourself

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

If you have ever built a webpage with vanilla JS or jQuery, you remember the dance. Click a button, find the element, change its text, also flip a class on its sibling, also hide that other thing over there, oh and update the counter in the header, do not forget the counter. Now multiply that by twenty interactions on the page, and you have a small horror movie.

The bug is almost always the same: the DOM said one thing, your variables said another, and they slowly drifted apart. You spent your evening pushing pixels around by hand.

That is the gap React fills.

What is React, really

Think of React as a smart artist who paints whatever you describe. You hand them a sentence: "a happy cat with a hat, named Mochi, age 2". They paint exactly that. Later, when Mochi turns 3, you do not erase and repaint the whole canvas. You just hand the artist a new sentence, and the artist quietly changes only what is different. The hat stays. The smile stays. The age becomes 3.

You are no longer the painter. You are the writer. You describe what the screen should look like for a given state. React figures out how to make the real DOM match. That is the whole magic.

This style has a name: declarative UI. You declare the destination, React handles the path.

Let's pretend we are building one

We want a way to build interactive UIs without spending our lives synchronizing variables with the DOM. We will call it React. Every decision we make will be something you see in real React code, so let's make them on purpose.

For our running example, we are going to build a tiny Cat Adoption Wall, growing it piece by piece.

Decision 1: UI is built from small reusable pieces

We will call them components. A component is just a function that takes some inputs and returns a description of what to draw. Pure JavaScript, nothing magical.

function CatCard() {
  return (
    <div className="card">
      <h2>Mochi</h2>
      <p>Looking for a cozy lap.</p>
    </div>
  );
}

That HTML looking thing inside the function is not HTML. It is JSX, which is just a friendlier way of writing React.createElement(...). A build tool (Vite, Next.js, whatever) turns it into real JavaScript before it ships.

Two rules of JSX that bite newcomers:

Use className instead of class, and htmlFor instead of for. Reason: class and for are reserved words in JS.
Every element you return must be wrapped in a single parent. If you do not want an extra <div>, use the empty fragment tags: <>...</>.

Components compose. A bigger component just calls smaller ones:

function AdoptionWall() {
  return (
    <main>
      <h1>Cats looking for a home</h1>
      <CatCard />
      <CatCard />
      <CatCard />
    </main>
  );
}

Three identical cats. That is not very useful yet. Let's make them different.

Decision 2: Pass data in with props

A component should be reusable, so we let callers pass values in. We will call them props (short for "properties"). They are just function arguments.

function CatCard({ name, bio, age }) {
  return (
    <div className="card">
      <h2>{name}</h2>
      <p>{bio}</p>
      <small>{age} years old</small>
    </div>
  );
}

function AdoptionWall() {
  return (
    <main>
      <h1>Cats looking for a home</h1>
      <CatCard name="Mochi"   bio="Looking for a cozy lap." age={2} />
      <CatCard name="Whiskers" bio="Loves boxes."           age={4} />
      <CatCard name="Pepper"   bio="Will steal your snack." age={1} />
    </main>
  );
}

Curly braces {} inside JSX mean "pop out into JavaScript for a moment". Anything that returns a value works inside there: variables, function calls, ternaries, even other JSX.

Important rule: props flow down, not up. A parent gives data to a child. A child should not reach up and change the parent's data directly. We will see how data flows back up in a moment.

Decision 3: When data changes, the screen should change too

A static page is not a UI. We need something that, when it changes, makes React repaint the relevant parts. We will call it state, and the way you ask for some is the useState hook.

import { useState } from "react";

function LikeButton() {
  const [likes, setLikes] = useState(0);

  return (
    <button onClick={() => setLikes(likes + 1)}>
      Mochi has {likes} likes
    </button>
  );
}

Read that first line out loud:

"Give me a piece of state called likes, starting at 0, and a setter to change it."

The trick: every time you call setLikes, React schedules a re-render. It calls your component function again. The function returns a fresh description of the UI based on the new value. React diffs the new description against the previous one and only touches the parts that actually changed in the real DOM.

You did not move any pixels. You did not query any elements. You changed a variable, and the screen followed.

A few things worth burning into memory, because they trip up everyone:

State is per component instance. Two LikeButtons on the page have two independent counters.
Updates are not instant. setLikes(likes + 1) schedules an update. Right after that line, likes is still the old value in the current function call.
For updates that depend on the current value, use the function form: setLikes((prev) => prev + 1). This is safer when multiple updates queue up.
Treat state as immutable. Do not mutate arrays or objects in place. Replace them with new ones: setCats([...cats, newCat]), not cats.push(newCat). React decides whether to re-render by comparing references, so a mutated array looks identical and nothing happens.

That last rule is the source of about half of all "why is my UI not updating" bugs.

Decision 4: Lists need a stable identity

When we render an array of things, React needs to tell them apart between renders, so it knows which item moved, which got deleted, and which is new. We give every item a key:

function AdoptionWall({ cats }) {
  return (
    <main>
      <h1>Cats looking for a home</h1>
      {cats.map((cat) => (
        <CatCard key={cat.id} {...cat} />
      ))}
    </main>
  );
}

The key should be something stable and unique inside that list. A database id is perfect. The array index is not good enough as soon as items can be reordered or deleted, because the index of an item changes when its neighbors change. Wrong keys lead to weird bugs where typed text jumps to a different row, or animations apply to the wrong item.

Decision 5: Children talk back through callbacks

Props go down. To send something back up, the parent passes a function down, and the child calls it.

function CatCard({ cat, onAdopt }) {
  return (
    <div className="card">
      <h2>{cat.name}</h2>
      <button onClick={() => onAdopt(cat.id)}>Adopt</button>
    </div>
  );
}

function AdoptionWall() {
  const [cats, setCats] = useState(initialCats);

  function handleAdopt(id) {
    setCats((prev) => prev.filter((c) => c.id !== id));
  }

  return (
    <main>
      {cats.map((cat) => (
        <CatCard key={cat.id} cat={cat} onAdopt={handleAdopt} />
      ))}
    </main>
  );
}

The cat list lives in AdoptionWall. The button lives in CatCard. They communicate through onAdopt. This pattern is called lifting state up: when two components need to share a piece of state, you move it up to their nearest common ancestor.

If lifting starts to feel painful (you are passing the same prop through five layers), that is your hint to reach for one of the tools below. Not before.

Decision 6: Sometimes you need to talk to the outside world

State is for things React owns. But the outside world exists too: timers, websockets, the document title, browser APIs, third party widgets. We need an escape hatch to sync with those, and we call it useEffect.

import { useEffect } from "react";

function PageTitle({ count }) {
  useEffect(() => {
    document.title = `${count} cats waiting`;
  }, [count]);

  return null;
}

Two things to know:

The function inside runs after React updates the DOM.
The array at the end is the dependency list. React reruns the effect only when one of those values changes.

Modern advice (this is important): useEffect is for synchronizing with external systems, not for "do this thing when the user clicks". For that, just use the click handler. A good test: if removing your effect would not silently leak something or fall out of sync with the outside world, it probably should not be an effect.

The most common misuse is fetching data inside useEffect. It works, but it is a road full of footguns (race conditions, cache invalidation, double fetches in dev, no caching). The much better path lives in Decision 9.

Decision 7: Forms, the friendly version

Forms used to be where everyone gets stuck. React 19 made them dramatically nicer with Actions and the useActionState hook. You hand the form an async function, and React handles the pending state, the result, and the form reset for you.

import { useActionState } from "react";

async function adoptCat(prev, formData) {
  const name = formData.get("name");
  const res  = await fetch("/api/adopt", { method: "POST", body: formData });
  if (!res.ok) return { error: "Could not adopt" };
  return { ok: true, message: `${name} is going home` };
}

function AdoptForm() {
  const [state, formAction, pending] = useActionState(adoptCat, null);

  return (
    <form action={formAction}>
      <input name="name" placeholder="Cat name" />
      <button type="submit" disabled={pending}>
        {pending ? "Sending..." : "Adopt"}
      </button>
      {state?.error   && <p style={{ color: "red"   }}>{state.error}</p>}
      {state?.message && <p style={{ color: "green" }}>{state.message}</p>}
    </form>
  );
}

That single hook replaces the classic "three useStates plus a try/catch plus a loading flag" pattern. The companion hook useFormStatus() works inside any descendant of the form and tells you pending, data, method, action. No prop drilling needed for a submit button to know its form is busy.

For richer forms with lots of fields and validation rules, reach for React Hook Form. It is the de facto choice in 2026. It avoids unnecessary re-renders and pairs nicely with Zod for type safe validation.

Decision 8: Show users instant feedback with `useOptimistic`

When the user clicks "Adopt", we do not want to make them stare at a spinner for 400ms. We want the cat to disappear from the wall instantly, and only roll back if the server says no.

React 19 ships a hook for exactly that:

import { useOptimistic } from "react";

function AdoptionWall({ cats }) {
  const [optimisticCats, removeOptimistic] = useOptimistic(
    cats,
    (current, idToRemove) => current.filter((c) => c.id !== idToRemove),
  );

  async function handleAdopt(id) {
    removeOptimistic(id);          // UI updates right now
    await fetch(`/api/adopt/${id}`, { method: "POST" });
    // when the real cats list refreshes, the optimistic state goes away
  }

  return optimisticCats.map((cat) => (
    <CatCard key={cat.id} cat={cat} onAdopt={handleAdopt} />
  ));
}

If the request fails, React swaps back to the real list automatically. You write the happy path, the framework handles the rollback.

Decision 9: State management, told straight

Here is the truth that the React ecosystem learned the hard way and finally agreed on:

Server state and client state are different problems. Stop solving them with the same tool.

Server state is data that lives somewhere else (a database, an API). It needs caching, refetching, retries, deduping, and invalidation. Client state is just stuff your UI cares about: which tab is open, is the sidebar collapsed, what theme are we in.

The 2026 default playbook looks like this:

Kind of state	Tool	Why
Local component state	`useState` / `useReducer`	It does not need to leave the component.
Form state	React Hook Form (+ Zod)	Fewer re-renders, great validation story.
Server data	TanStack Query (React Query)	Caching, refetching, loading flags, all for free.
Global UI state	Zustand	Tiny store, one hook to read and write, no boilerplate.
Atomic / fine grained	Jotai	When many small bits of state should react independently.
Big enterprise app	Redux Toolkit	Strict patterns, devtools, time travel debugging.

Here is the trap to avoid: do not fetch data with fetch inside useEffect and shove the result into Zustand or Redux. That is the most common anti pattern in 2026. You end up reinventing caching, you forget to invalidate, you fight stale data. Use TanStack Query for anything that came from a server.

A taste of each.

TanStack Query for server data

import { useQuery } from "@tanstack/react-query";

function AdoptionWall() {
  const { data: cats, isLoading, error } = useQuery({
    queryKey: ["cats"],
    queryFn:  () => fetch("/api/cats").then((r) => r.json()),
  });

  if (isLoading) return <p>Loading...</p>;
  if (error)     return <p>Something went wrong</p>;

  return cats.map((cat) => <CatCard key={cat.id} cat={cat} />);
}

Caching, retry, background refetch, dedupe across components, all included.

Zustand for global UI state

// stores/ui.js
import { create } from "zustand";

export const useUIStore = create((set) => ({
  theme: "light",
  toggleTheme: () => set((s) => ({ theme: s.theme === "light" ? "dark" : "light" })),
}));

function ThemeToggle() {
  const theme       = useUIStore((s) => s.theme);
  const toggleTheme = useUIStore((s) => s.toggleTheme);
  return <button onClick={toggleTheme}>Theme: {theme}</button>;
}

No provider to wrap your app in, no reducers, no actions, no boilerplate. One file, one hook, done.

Context for very small global stuff

Built into React, free. Best for things that rarely change: theme, current user, locale. Do not use Context as a state manager for fast changing state, because every consumer re-renders when the value changes. Use Zustand instead and you get cheap selector subscriptions.

const ThemeContext = createContext("light");

function App() {
  return (
    <ThemeContext.Provider value="dark">
      <Page />
    </ThemeContext.Provider>
  );
}

function Page() {
  const theme = useContext(ThemeContext);
  return <p>Current theme: {theme}</p>;
}

Decision 10: Move work to the server when you can

For the longest time, every React app shipped a giant bundle of JavaScript, then asked the user's browser to do everything: fetch data, render markup, hydrate, run interactivity. That is a lot of work to do in the laggy place.

React 19 leaned into a different idea: Server Components and Server Actions. A server component runs on the server, can read from a database directly, and ships only the rendered output to the browser. A server action is just an async function marked "use server" that the client can call like a local function, but it actually runs on the server. No API route needed.

// app/cats/page.jsx, a Server Component (Next.js style)
import { db } from "@/lib/db";
import AdoptButton from "./AdoptButton";

export default async function CatsPage() {
  const cats = await db.cat.findMany();
  return cats.map((cat) => (
    <div key={cat.id}>
      <h2>{cat.name}</h2>
      <AdoptButton id={cat.id} />
    </div>
  ));
}

// AdoptButton.jsx, a Client Component
"use client";

import { adoptCat } from "./actions";

export default function AdoptButton({ id }) {
  return <button onClick={() => adoptCat(id)}>Adopt</button>;
}

// actions.js
"use server";

import { db } from "@/lib/db";

export async function adoptCat(id) {
  await db.cat.update({ where: { id }, data: { adopted: true } });
}

The mental model:

Default to Server Components. They are cheaper, they keep secrets safe, they do not send code to the browser.
Add "use client" only on the small islands that actually need interactivity (a button, a form, a dropdown).
For mutations, write a function with "use server" and call it. No API route to hand roll.

You do not get Server Components in a plain Vite SPA. You get them in a framework like Next.js (App Router) or React Router 7 (Framework Mode). For a classic single page app, Vite + React + TanStack Query + Zustand is still excellent and very common in 2026.

Decision 11: A few more goodies in React 19

use() lets you read a Promise (or a Context) inside a component and have React suspend until it resolves. Pairs beautifully with Suspense and Server Components.
useTransition marks an update as "not urgent". The UI stays responsive while the heavy update happens in the background, and you get a pending flag for free. In React 19, the function passed to it can be async.
ref is now just a prop. No more forwardRef wrapping. You take ref like any other prop.
<title>, <meta>, <link> work anywhere. React hoists them into the document head for you, so SEO and head tags no longer need a separate library.
Better error messages for hydration mismatches, plus an automatically wired Document Metadata system.

You do not need any of this on day one. Knowing it exists means you will recognize it when you see it.

A peek under the hood

What really happens when you click a button in a React app:

Your onClick handler runs and calls setSomething(newValue).
React marks that component (and the tree below it) as "needs to re-render".
React calls your component function again. It gets back a new tree of JSX, in memory only. This in memory tree is sometimes called the virtual DOM.
React compares the new tree to the previous one. This is reconciliation. It figures out the smallest set of real DOM changes that would make reality match the new tree.
It applies only those changes to the real DOM.
After the DOM is committed, any useEffect whose dependencies changed runs.

That is why React feels fast even when you "render the whole thing on every state change". You do not actually rebuild the DOM, you rebuild a cheap description of it, and only the diff hits the real page.

Tiny tips that will save you later

Start with useState. Add libraries when you actually feel the pain.
Never store server data in client state. Use TanStack Query.
Treat state as immutable. No .push, no obj.x = y. Always make a new value.
Use the function form of setters when the next value depends on the previous: setCount((c) => c + 1).
Pick stable keys for lists. The array index is a trap as soon as items can move.
Effects sync with the outside world. They are not a "do something on click" tool.
Lift state to the lowest common parent that needs it, not to the top of the app.
Reach for Server Components and Server Actions when you can. Less JS shipped to the user, and your secrets stay on the server.
Default form library: React Hook Form + Zod. Default data fetcher: TanStack Query. Default global UI store: Zustand. You can build 95% of an app with that trio.
Use Vite for SPAs and Next.js (or React Router 7) for full apps. Avoid create-react-app, it has been retired.

Wrapping up

So that is the whole story. We were tired of pushing pixels around by hand. We built a framework where you describe what the UI should be for a given state, and the framework handles how to make the screen match. We broke the UI into small functions called components. We let them take props down and call functions up. We added state to make things change, effects to talk to the outside world, and a tidy little pipeline of modern hooks (useActionState, useOptimistic, useTransition, use) to handle async work without pain.

Then we admitted that not every piece of state is the same:

Local stuff stays in useState.
Forms go to React Hook Form.
Anything from a server goes to TanStack Query.
Shared UI state goes to Zustand.
Server work goes to Server Components and Server Actions.

Once that map is in your head, every React tutorial, blog post, and codebase starts to feel familiar. You stop fighting the framework and start moving at speed.

Happy rendering, and give your virtual cat a virtual scratch from me.

Learning TailwindCSS As If You Built It Yourself

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

If you have ever opened a year old CSS file and tried to figure out which class does what, you remember the feeling. card-2, card-2-blue, card-2-blue-mobile, card-2-blue-mobile-final, all in different files, all targeting the same component, all "almost" doing the same thing. Renaming any of them is risky. Deleting any of them is scarier. So nobody does, and the file grows forever.

That graveyard of dead classes is what Tailwind was invented to prevent.

What is TailwindCSS, really

Think of Tailwind as a tool belt of pre cut Lego bricks for styling. Instead of inventing class names like card-header-title-medium-blue and writing CSS for them, you snap together a handful of small, single purpose classes right in your HTML:

<div class="rounded-lg bg-white p-6 shadow">
  <h2 class="text-xl font-semibold text-slate-900">Mochi</h2>
  <p class="mt-2 text-slate-600">A small white cat with big plans.</p>
</div>

Each class does exactly one thing. rounded-lg is just border-radius: 0.5rem. p-6 is just padding: 1.5rem. There is no naming meeting. There is no dead CSS. The styles live next to the markup that uses them. When you delete the markup, the styles go with it.

Two ideas drive the whole thing:

Utility first. You compose your design from many tiny utilities, not from a few "components" that grow attribute soup over time.
Constrained, not free. The utilities only exist for the values you defined as design tokens (spacing scale, color palette, font sizes). You cannot accidentally write padding: 13.7px. You can only pick from p-1, p-2, p-3, etc. The constraint is the point.

That is the whole vibe.

Let's pretend we are building one

We want a way to write CSS that scales to a team and a year, without inventing names, without dead code, without a fight in code review every Monday. We will call it Tailwind.

For the running example, we are styling a small profile card with a name, an avatar, a bio, and two buttons. We will grow it piece by piece.

Decision 1: Ship a sensible default scale

We need a small, consistent set of values for spacing, type, and color. If everything is on the scale, components will feel like they were designed by the same person, even if 12 different people wrote them.

The defaults that ship with Tailwind:

Spacing: a 0.25rem (4px) base. p-1 = 4px, p-2 = 8px, p-4 = 16px, p-8 = 32px. Same scale used by margin, gap, width, height.
Type: text-xs, text-sm, text-base, text-lg, text-xl, text-2xl, all the way up to text-9xl. Each comes with a sensible line height.
Colors: 22 named color families (slate, gray, red, green, blue, indigo, ...) with 11 shades each (50 to 950). Plus full opacity control (text-blue-500/50, half opacity).
Radii, shadows, borders: also on a scale. rounded, rounded-md, rounded-lg, rounded-2xl. shadow-sm, shadow, shadow-md, shadow-lg.

The full classes look like this in a real component:

<button class="
  inline-flex items-center gap-2
  rounded-md
  bg-blue-600 px-4 py-2
  text-sm font-medium text-white
  hover:bg-blue-500
  focus-visible:outline-2 focus-visible:outline-blue-600 focus-visible:outline-offset-2
  disabled:opacity-50 disabled:cursor-not-allowed
">
  Adopt
</button>

Read it like a sentence, left to right. Layout, then box, then color, then text, then states. Once your eye adjusts (give it a week), it is faster to scan than CSS files split across the repo.

Decision 2: Variants for state and screen size

Plain CSS uses :hover and @media. Tailwind gives you the same power as prefixes on the class name.

<a class="
  text-slate-700
  hover:text-slate-900
  focus-visible:underline
  active:text-slate-950
">Read more</a>

<div class="
  grid
  grid-cols-1
  md:grid-cols-2
  lg:grid-cols-3
  gap-4
">...</div>

The state prefixes you will reach for daily:

hover:, focus:, focus-visible:, active:, disabled:
group-hover: and peer-hover: for "when my parent or sibling is hovered" (super useful)
aria-expanded:, aria-checked:, data-[state=open]: for components driven by ARIA or data attributes
has-[:invalid]: for the new CSS :has() selector
not-first:, first:, last:, odd:, even:

The screen prefixes (mobile first):

sm: 640px and up
md: 768px and up
lg: 1024px and up
xl: 1280px and up
2xl: 1536px and up

Read md:grid-cols-2 as "from 768px and up, use two columns". The bare class is the mobile baseline.

You can stack prefixes:

<button class="
  bg-blue-600 hover:bg-blue-500
  md:bg-emerald-600 md:hover:bg-emerald-500
">Multi state</button>

Variants are how Tailwind avoids the "one giant CSS file with sixteen media queries" problem. The state lives next to the value.

Decision 3: Dark mode is just another variant

<div class="bg-white text-slate-900 dark:bg-slate-900 dark:text-slate-100">
  ...
</div>

In Tailwind v4, dark: defaults to the user's prefers-color-scheme. If you want a manual toggle (a moon icon in your nav), you opt into the class strategy:

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

Then <html class="dark"> flips your whole site.

Decision 4: Configuration, the v4 way

Tailwind used to live in a tailwind.config.js. Tailwind v4 (the current major in 2026) moved configuration into CSS itself. You define design tokens with @theme, and Tailwind generates utilities for you automatically.

/* app.css */
@import "tailwindcss";

@theme {
  --color-brand:    oklch(63% 0.16 256);
  --color-brand-50: oklch(96% 0.02 256);

  --font-display: "Inter", system-ui, sans-serif;

  --spacing-128: 32rem;

  --radius-card: 1.25rem;

  --breakpoint-3xl: 1920px;
}

Defining --color-brand automatically gives you bg-brand, text-brand, border-brand, ring-brand. Defining --spacing-128 gives you p-128, mx-128, w-128. Defining --breakpoint-3xl gives you 3xl:.

That is the whole config story now. No JS file, no theme.extend, no rebuilding the world.

If you need full power, the JS config still works for backwards compatibility. New projects should start in CSS.

Decision 5: Arbitrary values for the rare one off

Sometimes you need a specific pixel value that is not on the scale. The escape hatch is square brackets:

<div class="w-[317px] mt-[7px] grid-cols-[200px_1fr_60px]">...</div>
<p class="text-[#bada55]">design demanded a specific hex</p>
<div class="bg-[url('/hero.jpg')]">...</div>

Useful, but be honest with yourself. If the same arbitrary value appears more than twice, it should be a token in @theme, not an inline literal.

You can also use modifiers for opacity, font weight, etc:

<div class="bg-blue-500/30 text-slate-900/80">
  30% blue background, 80% opaque text
</div>

Decision 6: Composition without losing your mind

Once a button shows up in twenty places with the same long class string, you want to deduplicate. Two senior level moves:

Component in your framework, not in CSS

The Tailwind opinion: a component is a React/Vue/Svelte component, not a .btn CSS class.

// Button.tsx
import { cva, type VariantProps } from "class-variance-authority";
import clsx from "clsx";

const button = cva(
  "inline-flex items-center gap-2 rounded-md font-medium transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 disabled:opacity-50",
  {
    variants: {
      kind: {
        primary:   "bg-blue-600 text-white hover:bg-blue-500 focus-visible:outline-blue-600",
        secondary: "bg-slate-200 text-slate-900 hover:bg-slate-300",
        ghost:     "text-slate-700 hover:bg-slate-100",
      },
      size: {
        sm: "px-3 py-1.5 text-sm",
        md: "px-4 py-2  text-sm",
        lg: "px-5 py-2.5 text-base",
      },
    },
    defaultVariants: { kind: "primary", size: "md" },
  }
);

type Props = VariantProps<typeof button> &
  React.ButtonHTMLAttributes<HTMLButtonElement>;

export function Button({ kind, size, className, ...rest }: Props) {
  return <button className={clsx(button({ kind, size }), className)} {...rest} />;
}

The pair you will see most: clsx (or classnames) for conditional class composition, tailwind-merge for safely overriding earlier classes (so <Button className="bg-red-500" /> actually wins), and class-variance-authority for typed component variants.

`@apply`, the rare exception

If a component is used in plain HTML (no framework), or if you need to style elements you do not control (like markdown HTML), you can extract a class with @apply:

@layer components {
  .prose-link {
    @apply text-blue-600 underline underline-offset-2 hover:text-blue-500;
  }
}

@apply is a tool, not a strategy. If you find yourself reaching for it everywhere, you are fighting Tailwind's grain. Use components instead.

Decision 7: Layouts with utilities

A side by side layout in pure utilities:

<header class="flex items-center justify-between gap-4 p-4 border-b">
  <h1 class="text-lg font-semibold">Mia's Blog</h1>
  <nav class="flex items-center gap-6 text-sm text-slate-600">
    <a class="hover:text-slate-900" href="/">Home</a>
    <a class="hover:text-slate-900" href="/about">About</a>
  </nav>
</header>

A responsive grid:

<section class="grid gap-6 grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 p-6">
  <article class="rounded-2xl bg-white p-6 shadow">...</article>
  <article class="rounded-2xl bg-white p-6 shadow">...</article>
  <article class="rounded-2xl bg-white p-6 shadow">...</article>
</section>

A modern landing hero with fluid type:

<section class="
  mx-auto max-w-3xl px-6 py-20 text-center
  bg-gradient-to-b from-slate-50 to-white
">
  <h1 class="text-balance text-4xl sm:text-5xl lg:text-6xl font-bold tracking-tight">
    A tiny library for tiny lives.
  </h1>
  <p class="mt-6 text-lg text-slate-600">
    Carefully selected books for slow afternoons.
  </p>
  <div class="mt-10 flex justify-center gap-3">
    <button class="rounded-md bg-slate-900 px-5 py-2.5 text-white hover:bg-slate-800">
      Browse
    </button>
    <button class="rounded-md px-5 py-2.5 text-slate-700 hover:bg-slate-100">
      Learn more
    </button>
  </div>
</section>

text-balance is a small modern win. It tells the browser to balance lines so the heading does not orphan a single word on its own line.

Decision 8: Container queries and modern CSS, free

Tailwind v4 ships container queries built in, no plugin needed.

<aside class="@container p-6">
  <article class="
    rounded-lg bg-white p-4
    @md:flex @md:items-center @md:gap-4
  ">
    <img class="h-20 w-20 rounded-full" src="/mochi.jpg" />
    <div class="@md:flex-1">
      <h3 class="text-lg font-semibold">Mochi</h3>
      <p class="text-sm text-slate-600">A small cat with big plans.</p>
    </div>
  </article>
</aside>

@md: triggers when the container crosses the md size, not the viewport. The same card looks different in a wide and a narrow column without changing its markup.

Other modern bits Tailwind exposes nicely:

has-[] for parent based styling: has-[:invalid]:border-red-500
group-has-[], peer-has-[] for descendant or sibling based logic
text-balance, text-pretty for typography
scroll-snap-x, snap-mandatory, snap-start for snap scrolling
backdrop-blur, backdrop-brightness for frosted glass UIs
mix-blend-multiply and other blend modes

Decision 9: Theming with CSS variables

Because v4 builds tokens as real CSS variables, runtime theming is free.

@theme {
  --color-brand: oklch(63% 0.16 256);
}

:root[data-theme="warm"]  { --color-brand: oklch(70% 0.15 30); }
:root[data-theme="cool"]  { --color-brand: oklch(70% 0.12 250); }
:root[data-theme="green"] { --color-brand: oklch(70% 0.15 150); }

Now bg-brand follows the data-theme attribute. Switching themes is one attribute change in JavaScript, no rebuild, no class swap on every component.

Decision 10: Forms and prose

Two official plugins worth installing on any content site:

@tailwindcss/forms gives all form elements consistent base styles you can build on. Without it, browser defaults are inconsistent across systems.
@tailwindcss/typography gives you a .prose class that styles raw HTML (from a CMS or markdown) beautifully. <article class="prose lg:prose-lg dark:prose-invert">{markdown}</article> is the whole setup.

Add them to app.css:

@import "tailwindcss";
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/typography";

(In v4, plugins are declared in CSS, not in a JS config.)

Decision 11: The headless component story

Tailwind only handles styles. Real apps need accessible behaviors: dropdowns with focus trap, dialogs that handle escape, comboboxes with type ahead. Hand rolling these is a graveyard.

The two friends to know:

Headless UI (from the Tailwind team): unstyled but accessible primitives. Bring your own utility classes.
Radix UI (or React Aria on the React side): a more comprehensive set of accessible primitives. Pairs beautifully with Tailwind.

Combine these with cva for variants and you have a small, fast, type safe component library that looks however you want.

Decision 12: Anti patterns, the senior level smell test

A handful of things that will rot your Tailwind codebase:

One giant @apply per component. You are reinventing CSS classes inside Tailwind. Extract a real component instead.
Random arbitrary values. w-[317px] once is fine. w-[317px] in 30 places is a missing token.
Inline string of 60 classes with no structure. Group by purpose: layout, then box, then color, then text, then states. Or use cva.
Skipping tailwind-merge when your component accepts className. Without it, callers cannot override.
Using @apply for components used inside React/Vue. You are halfway between two worlds. Pick one.
Hand rolling dropdowns and dialogs instead of using Headless UI or Radix. Accessibility lives there.
No design tokens. Without @theme variables, you lose the "constrained on purpose" benefit.

A peek under the hood

What really happens when Tailwind builds your CSS:

Tailwind scans your template files (HTML, JSX, Vue, Svelte, etc).
It finds every class string used.
For each class it recognizes, it generates the CSS rule that class needs.
Unused utilities are not generated. The output stylesheet only contains what your code actually uses.
The JIT (just in time) engine in v4 uses Rust under the hood and a new Lightning CSS based pipeline. Builds that used to take seconds now take milliseconds.
The output ships as one small CSS file.

That last point is why a "huge utility framework" still produces tiny stylesheets in production. You only get the classes you used. Delete a component, the styles disappear with it. There is no dead CSS.

Tiny tips that will save you later

Use the official VS Code extension. Autocomplete, hover docs, class sorting. Non negotiable.
Use the Prettier plugin (prettier-plugin-tailwindcss) for canonical class order. Code reviews stop arguing about it.
Set up tailwind-merge in any component that accepts className.
Define design tokens in @theme on day one. You will use them on day two.
Mobile first, always. Bare class is mobile. md: is tablet up.
Use cva for typed component variants. Avoid stringly typed className props with five conditionals.
Turn on text-balance for headings for free typography wins.
Wrap content with max-w-prose for readable line lengths.
Use Headless UI or Radix for any interactive component (modal, menu, combobox).
Audit unused arbitrary values every month or so. Promote the repeated ones into the theme.

Wrapping up

So that is the whole story. We were tired of inventing class names that aged into a graveyard. We built a system where styles are tiny single purpose classes, written next to the markup that uses them. Our design tokens are CSS variables defined in @theme. Our utilities respect a constrained scale, so layouts feel consistent across the team. Variants give us state and screen size right where the value is. Dark mode is just another variant. Container queries, :has(), OKLCH colors, and modern features all come along for free.

We learned to compose into framework components (with cva, clsx, tailwind-merge) instead of CSS components, to keep @apply rare, and to lean on Headless UI or Radix for accessible behavior. We got rid of dead CSS forever, because Tailwind only generates the classes our code actually uses.

Once that map is in your head, every Tailwind codebase starts to feel familiar, fast, and shockingly maintainable a year later. Tailwind stops feeling like "ugly inline styles" and starts feeling like the calm, constrained design system every team wishes it had.

Happy styling, and may your stylesheet stay small.

Learning TypeScript As If You Built It Yourself

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

If you have ever shipped a JavaScript app of any real size, you know the moment. It is 11pm. You renamed a function from getUser to loadUser. The app boots. Tests pass. You ship it. Twenty minutes later a coworker pings you: a button somewhere completely unrelated has stopped working, because something deep inside still called getUser and the editor never warned you.

JavaScript is full of these little knives. undefined is not a function. Cannot read property 'name' of null. A string that quietly was a number. An object missing a field. The compiler did not catch it because there was no compiler.

That is the gap TypeScript fills.

What is TypeScript, really

Think of TypeScript as a label maker for JavaScript values. In plain JS, every box in your warehouse looks the same: an unlabeled cardboard cube. You have to open it to know what is inside, and you might still be wrong. In TS, every box gets a sticker on the front that says exactly what kind of thing it holds. "string". "User". "Array of pizzas". A picky little manager called the type checker walks the aisles and yells at you if you try to put a tomato in the box labeled "books".

That manager only works at build time. Once you ship, the labels are stripped off and the boxes go to production as plain JS. So you pay zero runtime cost for all that safety.

That is the whole vibe.

Let's pretend we are building one

We want to add a type system on top of JavaScript without breaking anything that already works. We will call it TypeScript. As we design it, every decision is a thing you will run into in real code, so let's make them on purpose.

For the running example, we are opening a tiny pizza shop. Pizzas, toppings, sizes, orders. We will type the whole thing as we go.

Decision 1: Types are notes for the compiler, not new runtime stuff

We do not want to invent a new language. We want JavaScript with extra notes on top. So our compiler will read the notes, check them, and then erase them. The JS that ships to production is the same JS you would have written without types.

function add(a: number, b: number): number {
  return a + b;
}

After compilation, the file becomes:

function add(a, b) {
  return a + b;
}

The labels are gone at runtime. This has two huge consequences that newcomers miss:

You cannot trust types at runtime. If data comes from an API, a form, or JSON.parse, the type system has no idea what is actually in there. You have to validate it (with Zod, Valibot, or a hand written guard).
No new runtime features (mostly). Old TypeScript tried with enum, decorators, and namespace. The modern advice is to avoid enum and prefer plain unions of strings.

Decision 2: Start with the basics, give two escape hatches

Our type system needs the obvious primitives, plus a way to say "I do not know yet" without giving up on safety entirely.

let title:   string  = "Margherita";
let price:   number  = 9.5;
let isOpen:  boolean = true;
let nothing: null    = null;
let missing: undefined = undefined;

let everything: any     = "literally anything";   // do not use, opts out of safety
let mystery:    unknown = "could be anything";    // safe version of any
function explode(): never { throw new Error("boom"); } // function never returns
function log(msg: string): void { console.log(msg); } // does not return a value

Two escape hatches matter a lot:

any turns off the type checker for that value. Treat it like a swear word. The whole point of TS is to know what you have, and any says "I do not know and I do not want to". Use only as a last resort, and isolate it.
unknown also says "I do not know yet", but the compiler refuses to let you do anything with it until you prove what it is (with a check or a guard). This is the right tool for incoming data.

function readInput(value: unknown) {
  // value.toUpperCase()  // error: object is of type 'unknown'
  if (typeof value === "string") {
    value.toUpperCase(); // ok now, narrowed to string
  }
}

never is the bottom type, the type with no values. It shows up when something is logically impossible (a function that always throws, or a switch branch that should never be reached). We will use it as a tool later for exhaustiveness.

Decision 3: Describe object shapes with `type` or `interface`

A pizza is not just a string. It is a shape with a name, a size, toppings, and a price. We need to describe shapes.

type Pizza = {
  id:       string;
  name:     string;
  size:     "small" | "medium" | "large";
  toppings: string[];
  priceCents: number;
};

Two ways to write this exist, and they confuse newcomers. There are type aliases and interface declarations:

interface Pizza {
  id: string;
  name: string;
  // ...
}

Practical advice in 2026:

Use type by default. It can do everything interface can, plus unions, intersections, mapped types, and conditional types.
Use interface when you need declaration merging (mostly for adding fields to library types) or when you are publishing a public class API.
Be consistent inside one project. Do not flip flop.

A nice fact about TypeScript that surprises people coming from Java or C#: types are structural, not nominal. If two shapes look the same, they are the same. Names do not matter to the checker.

type Cat = { name: string; age: number };
type Dog = { name: string; age: number };

const meow: Cat = { name: "Mochi", age: 2 };
const woof: Dog = meow; // perfectly fine, shapes match

This is amazing for flexibility. Sometimes too flexible (we will fix that with branded types later).

A few small tricks worth knowing about object types:

type Pizza = {
  readonly id: string;       // cannot be reassigned after creation
  description?: string;      // optional, may be undefined
  [key: string]: unknown;    // index signature: any extra keys allowed
};

Decision 4: Combine, pick, choose

Real types are not always one shape. They are "this or that", or "this and that".

Union types: `A | B`

type Size = "small" | "medium" | "large";

function priceFor(size: Size): number {
  if (size === "small")  return 800;
  if (size === "medium") return 1100;
  return 1400;
}

Those "small" | "medium" | "large" are literal types. A literal type is a type whose only value is one specific value. This is how we get the "enum like" experience without the actual enum keyword.

Intersection types: `A & B`

type WithTimestamps = { createdAt: Date; updatedAt: Date };
type StoredPizza   = Pizza & WithTimestamps;

A StoredPizza is everything a Pizza is, and has timestamps too.

Discriminated unions, the secret weapon

This is the single most useful pattern in real TypeScript. When something can be in multiple shapes depending on a state, give every variant a common literal field, and the checker can tell them apart.

type Order =
  | { status: "pending";   pizzaId: string }
  | { status: "cooking";   pizzaId: string; ovenId: string }
  | { status: "delivered"; pizzaId: string; deliveredAt: Date }
  | { status: "cancelled"; reason: string };

function describe(order: Order): string {
  switch (order.status) {
    case "pending":   return `Pending pizza ${order.pizzaId}`;
    case "cooking":   return `Cooking in oven ${order.ovenId}`;
    case "delivered": return `Delivered at ${order.deliveredAt.toISOString()}`;
    case "cancelled": return `Cancelled: ${order.reason}`;
  }
}

Inside each case, TypeScript narrows the type and gives you only the fields that exist for that variant. No more "is this property here on this kind of order? let me check the docs".

Add a final exhaustiveness check using never and the compiler will literally yell at you when a future you adds a new status and forgets to handle it:

function describe(order: Order): string {
  switch (order.status) {
    case "pending":   return ...;
    case "cooking":   return ...;
    case "delivered": return ...;
    case "cancelled": return ...;
    default: {
      const _exhaustive: never = order;
      return _exhaustive;
    }
  }
}

Add a new case to Order later, forget to add a branch, and that line lights up red. Free safety net.

Decision 5: Make types reusable with generics

We do not want to write a new shape for "an array of pizzas", "an array of orders", "an array of users". The shape is the same: an array, holding things of some type. So we let the user fill in the blank.

type Box<T> = { value: T };

const numberBox: Box<number> = { value: 42 };
const pizzaBox:  Box<Pizza>  = { value: somePizza };

The T is a type parameter. Read it as "for any type T, a Box of T is...".

Generics shine in functions:

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const p = first([pizza1, pizza2]); // p is Pizza | undefined
const n = first([1, 2, 3]);        // n is number | undefined

You did not have to tell first what type was in there. The compiler inferred it from the argument. Inference is one of TypeScript's superpowers. Lean on it. Do not annotate things the compiler can already figure out.

You can constrain a type parameter, so it has to satisfy some shape:

function getId<T extends { id: string }>(item: T): string {
  return item.id;
}

Now T can be anything, as long as it has an id: string.

Real world examples you will see daily:

type ApiResult<T> =
  | { ok: true;  data: T }
  | { ok: false; error: string };

async function fetchPizza(id: string): Promise<ApiResult<Pizza>> { /* ... */ }

That single pattern (a generic discriminated union) replaces about 80% of "what should the return type be" questions.

Decision 6: Ship a standard library of utility types

Once we have generics, conditionals, and mapped types (more on those soon), we can pre build a bunch of "type level functions" that everyone needs. These come with the language.

The greatest hits:

type P = Partial<Pizza>;    // every field optional
type R = Required<Pizza>;   // every field required (strips ?)
type O = Readonly<Pizza>;   // every field readonly
type N = NonNullable<string | null | undefined>; // string

type Just = Pick<Pizza, "id" | "name">;       // only those keys
type Without = Omit<Pizza, "priceCents">;     // every key except those

type Menu = Record<string, Pizza>;            // an object map: keys -> Pizza

type Args = Parameters<typeof priceFor>;      // tuple of arg types: [Size]
type Ret  = ReturnType<typeof priceFor>;      // number

type Awaited1 = Awaited<Promise<Pizza>>;      // unwraps promises: Pizza

type SizeOnly = Extract<Size, "small" | "medium">;  // narrowing a union
type NotSmall = Exclude<Size, "small">;             // removing from a union

Memorize these. They make 90% of "how do I express this type" problems trivial.

Decision 7: Narrow types as you learn more

The compiler tracks what you know about a value as the code runs. Each check makes the type more specific. This is narrowing, and the rules are:

function area(x: string | number) {
  if (typeof x === "string") {
    x.toUpperCase();   // here x is string
  } else {
    x.toFixed(2);      // here x is number
  }
}

class Pizza { eat() {} }
class Salad { dress() {} }

function feed(food: Pizza | Salad) {
  if (food instanceof Pizza) food.eat();
  else                       food.dress();
}

function hasName(v: object): boolean {
  if ("name" in v) return true;  // narrows to { name: unknown } & object
  return false;
}

For checks the compiler cannot figure out on its own, write a type predicate. It teaches the checker your custom logic:

function isPizza(x: unknown): x is Pizza {
  return typeof x === "object" && x !== null && "toppings" in x;
}

const stuff: unknown = await fetchSomething();
if (isPizza(stuff)) {
  stuff.toppings; // ok, narrowed to Pizza
}

Type predicates are how you bring messy outside data into your typed world. For real production code, prefer a runtime schema validator like Zod that gives you the predicate and the type at the same time:

import { z } from "zod";

const PizzaSchema = z.object({
  id: z.string(),
  name: z.string(),
  size: z.enum(["small", "medium", "large"]),
  toppings: z.array(z.string()),
  priceCents: z.number().int().nonnegative(),
});

type Pizza = z.infer<typeof PizzaSchema>; // type derived from the schema

const pizza = PizzaSchema.parse(unknownInput); // throws if invalid

One schema, both runtime validation and the static type. This is the modern standard at the API boundary.

Decision 8: Let people compute new types from old ones

This is the part that makes TypeScript feel like a tiny programming language at the type level. Powerful, sometimes a little spooky.

Mapped types

Walk over the keys of one type and produce another.

type Optional<T> = { [K in keyof T]?: T[K] };
type ReadonlyDeep<T> = { readonly [K in keyof T]: T[K] };

type DraftPizza = Optional<Pizza>; // every field optional

Partial, Required, Readonly, and friends are all built with mapped types behind the scenes.

Conditional types

If A is a subtype of B, do this, else do that.

type IsString<T> = T extends string ? "yes" : "no";

type A = IsString<"hello">; // "yes"
type B = IsString<42>;      // "no"

Combined with infer, you can pull pieces out of types:

type ElementOf<T> = T extends (infer U)[] ? U : never;

type Topping = ElementOf<Pizza["toppings"]>; // string

Template literal types

Strings as types, with interpolation.

type EventName<T extends string> = `on${Capitalize<T>}`;

type X = EventName<"click">; // "onClick"

You can build wild route type DSLs with these (think "/users/:id" inferring the parameter names), but for daily work, the value is mostly readable string keys.

`keyof` and indexed access

type PizzaKeys = keyof Pizza; // "id" | "name" | "size" | "toppings" | "priceCents"
type SizeType  = Pizza["size"]; // "small" | "medium" | "large"

These two operators are how you keep types in sync. If Pizza changes, anything derived from keyof Pizza updates automatically.

Decision 9: Three modern features that level you up

`as const` for "freeze this exactly"

By default, the compiler widens literal values. const x = "small" becomes type string. If you want the literal type, freeze it:

const SIZES = ["small", "medium", "large"] as const;
type Size = typeof SIZES[number]; // "small" | "medium" | "large"

That last line is gold. It builds the union type directly from the array, so you can never get them out of sync.

`satisfies` for "fits this shape, but keep the specific type"

A common annoying choice in old TS: do I annotate this as Record<string, Pizza> (and lose the specific keys), or leave it untyped (and lose the shape check)? satisfies solves both at once.

const menu = {
  margherita: { id: "1", name: "Margherita", size: "small",  toppings: [],            priceCents: 800  },
  pepperoni:  { id: "2", name: "Pepperoni",  size: "medium", toppings: ["pepperoni"], priceCents: 1100 },
} satisfies Record<string, Pizza>;

menu.margherita.name; // ok, autocomplete works
menu.unknownPizza;    // error, key does not exist

The compiler verified each entry is a valid Pizza, but menu keeps its specific keys. Use satisfies whenever you would have reached for as. It is safer.

Branded types for nominal typing on the cheap

Structural typing means a UserId and a PizzaId are the same type if they are both strings. Sometimes you do not want that.

type Brand<T, B> = T & { readonly __brand: B };

type UserId  = Brand<string, "UserId">;
type PizzaId = Brand<string, "PizzaId">;

function makePizzaId(s: string): PizzaId {
  return s as PizzaId;
}

function deletePizza(id: PizzaId) { /* ... */ }

const userId: UserId = "u_42" as UserId;
deletePizza(userId);              // error, not a PizzaId
deletePizza(makePizzaId("p_42")); // ok

The brand only exists at the type level. At runtime it is just a string. But the compiler will not let you mix them up. Use this any time a primitive (a string id, a number cents, a number millis) carries meaning that should not be mixed with another primitive of the same kind.

Decision 10: A `tsconfig.json` that prevents pain

The compiler is only as strict as you ask it to be. The settings below are what serious TypeScript codebases turn on. They prevent entire classes of bugs.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "DOM"],

    "strict": true,                      // turns on all the strict flags
    "noUncheckedIndexedAccess": true,    // arr[i] is T | undefined, not T
    "exactOptionalPropertyTypes": true,  // x?: number does not allow x: undefined
    "noImplicitOverride": true,          // override must say so

    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "forceConsistentCasingInFileNames": true,

    "isolatedModules": true,             // helps with bundlers and SWC
    "esModuleInterop": true,
    "skipLibCheck": true,                // faster builds, fewer 3rd party errors
    "verbatimModuleSyntax": true         // strict import type / export type
  }
}

The two flags every senior should know about beyond strict:

noUncheckedIndexedAccess turns array[i] and record[key] into T | undefined. Almost all "cannot read property of undefined" production bugs disappear when this is on, because the compiler now forces you to check.
exactOptionalPropertyTypes stops { name?: string } from secretly meaning { name?: string | undefined }. Subtle but it bites at API boundaries.

Turn these on early in a new project. They are pure gain.

Decision 11: Talk to the rest of the world

Type only imports and exports

When you import only types, mark them. The bundler removes them entirely, no chance of a runtime side effect:

import type { Pizza } from "./types";
import { makePizza } from "./factory";

With verbatimModuleSyntax: true, the compiler enforces this. It also kills accidental cycles caused by importing a value just for its type.

`.d.ts` declaration files

A .d.ts file is types only, no implementation. You write them when:

You publish a JS library and want to ship types separately.
You have a JS file in your project that you want to type from outside.
You want to add ambient types (like declaring process.env).

// env.d.ts
declare global {
  namespace NodeJS {
    interface ProcessEnv {
      DATABASE_URL: string;
      NODE_ENV: "development" | "production" | "test";
    }
  }
}
export {};

Now process.env.DATABASE_URL is typed as string, and a typo in the variable name is a compile error.

Module augmentation and declaration merging

Sometimes a library is missing a type or you want to extend it. Reopen the module and merge in fields:

// express.d.ts
import "express";

declare module "express" {
  interface Request {
    user?: { id: string; email: string };
  }
}

After this, req.user is typed everywhere, with no need to fork the package.

`@types/*` and DefinitelyTyped

If a JS only library does not ship types, look for @types/that-library on npm. It is published by the community DefinitelyTyped repo. If it does not exist, you can write a small .d.ts yourself with declare module "that-library"; to silence errors and add types as needed.

Senior level moves and traps

A handful of patterns and pitfalls you will run into at staff and senior level:

Prefer string unions over enum. Enums have weird runtime behavior, do not tree shake well, and break with isolatedModules. type Status = "open" | "closed" is simpler and erased.
Prefer unknown to any everywhere data crosses a boundary. Validate, then narrow.
Avoid type assertions (x as T) unless you genuinely know more than the compiler. Each as is a tiny lie. Reach for satisfies, type guards, or schema validators first.
Variance matters more than you think. Function parameters are contravariant, return types are covariant. If (a: Animal) => void is assignable where (a: Cat) => void is expected, that is why. Do not fight this, learn the rules.
Distributive conditional types kick in over naked unions. T extends X ? A : B distributes over each member of T if T is a union. Wrap in [T] to disable: [T] extends [X] ? A : B.
Do not over engineer types. A 200 line conditional type that infers a SQL schema looks impressive in a tweet and is a maintenance nightmare in a real project. Go simple first. Reach for fancy types only when they pay off in safety or DX you can feel.
Object.keys returns string[], not (keyof T)[]. This trips everyone. JS objects can have extra keys, so the standard library plays it safe. Cast only if you are sure: Object.keys(obj) as (keyof T)[].
readonly is shallow. readonly Pizza[] stops you from pushing, but the items inside are still mutable. Use DeepReadonly<T> (or the Readonly<T> mapped type recursively) when you need it.
Do not store types in classes if a type works. Classes carry runtime cost. Types are free.
Use NonNullable, Awaited, ReturnType, and Parameters to derive instead of duplicate. Single source of truth.
Keep types close to the code they describe. Co locating pizza.ts and pizza.types.ts (or just one file) beats a global types/ folder for everyone's sanity.

A peek under the hood

What really happens when you build a TS project:

The compiler (tsc) reads your tsconfig.json and walks every .ts/.tsx file in scope.
It builds a graph of types, doing inference where you did not annotate, then checks every assignment, call, and return.
If anything fails, it prints errors. Nothing is emitted by default in that case (unless noEmitOnError is off).
If checks pass, it emits plain .js files (and optionally .d.ts files for libraries).
At runtime, your code is just JavaScript. No types, no overhead, no surprises.

In modern projects, the build is often handled by a fast bundler (Vite, esbuild, SWC, Bun) that strips types blindly without type checking, while a separate tsc --noEmit runs in CI and your editor for the actual checking. Two jobs, two tools, both happy.

Tiny tips that will save you later

Lean on inference. Do not annotate variables the compiler already knows.
Annotate function signatures. Especially exported ones. They are your contract with the world.
Validate at the boundary. Schema in, typed everywhere after.
Use as const for static lookup tables. Use satisfies for typed but specific configs.
Brand IDs and units. A bug between user ids and pizza ids is one keystroke away without it.
Crank up strict plus noUncheckedIndexedAccess plus exactOptionalPropertyTypes on day one. Adding them later is painful.
Run tsc --noEmit in CI. Editor squiggles are not enough.
Read other people's types. The TS standard library, the React types, and Zod are masterclasses. Click through to definitions in your editor whenever you are curious.
Fancy types are a tool, not a flex. If a simple type works, use it.

Wrapping up

So that is the whole story. We were tired of JavaScript's quiet bugs. We invented a label maker that lives at the layer above the code. We wrote shapes with type and interface. We combined them with unions and intersections, and used discriminated unions for state. We made them reusable with generics, derived new ones with mapped and conditional types, and shipped a small standard library of helpers like Partial, Pick, and Awaited.

We added modern moves like as const, satisfies, and branded types to be precise without losing flexibility. We turned on the strictest flags so the compiler catches the most bugs. We validated at the edges with Zod, narrowed with type guards, and trusted the types only past that boundary.

Once that map is in your head, every TypeScript codebase starts to feel familiar. You stop fighting red squiggles and start using them as a free pair programmer who reads every line you write and quietly catches the future you about to make a mistake.

Happy typing, and put a slice aside for me.

Learning JavaScript As If You Built It Yourself

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

If you have ever wanted to make a webpage do something (anything) when you click a button, you have already met JavaScript. It is the only language that ships in every browser on the planet. It runs on servers, on robots, in databases, on watches, on toasters with WiFi.

It is also the language that confuses new developers more than any other, because it grew in layers over thirty years. Some parts feel modern and clean. Some parts feel like a haunted attic. Both parts ship in every browser, and both parts will outlive us.

That is the gap JavaScript fills, and the maze it creates.

What is JavaScript, really

Think of JavaScript as the electricity of the web. HTML gives a page its shape. CSS gives it style. JavaScript makes it move. Plug it in, things happen. It is the only language a browser understands natively, so if you want a website to react to a click, fetch some data, or animate a thing, you are using JavaScript whether you wrote it yourself or it came from a library.

The whole language follows three loud rules:

It runs on a single thread. One thing at a time. Long work blocks the page.
It is dynamically typed. A variable can hold a number now and a string later. The compiler does not stop you.
It is built around objects and functions. Functions are values. Objects are bags of values. That is most of it.

That is the whole vibe.

Let's pretend we are building one

We want a tiny scripting language that runs in the browser, can manipulate the page, and is friendly enough that anyone can pick it up. We will call it JavaScript. Every decision we make will show up in real code, so let's make them on purpose.

For our running example, we are building a tiny mood tracker. It saves a mood, lists moods, talks to a server. Small, but it lets us touch every important corner.

Decision 1: Variables, three flavors and the right default

const mood = "happy";
let count = 0;
var oldStyle = "do not use";

The cheat sheet:

const for values that will not be reassigned. Default to this.
let for values you actually need to reassign.
var is the old keyword. It is function scoped (not block scoped) and gets hoisted in confusing ways. Do not use var in new code.

const does not mean the value is frozen. It only means the binding does not change. const arr = [1, 2, 3]; arr.push(4) is fine. The variable still points at the same array, the array just got a new element.

Decision 2: Two kinds of values, and they behave differently

JavaScript has eight types, and they fall into two camps:

Primitives (passed by value, immutable): string, number, boolean, null, undefined, symbol, bigint.
Objects (passed by reference): everything else, including arrays and functions.

let a = 1;
let b = a;
b = 2;
// a is still 1

let x = { value: 1 };
let y = x;
y.value = 2;
// x.value is also 2, because x and y point at the same object

This single distinction explains about 30% of beginner bugs. If you mutate an object, every variable pointing at it sees the change.

A small note on the weird two: null is "intentionally nothing" and undefined is "no value yet". They are different types but most code treats them the same way. Use the loose equality just for them: value == null matches both.

Decision 3: Functions are first class

A function is a value. You can store it in a variable, pass it as an argument, return it from another function. This unlocks everything from callbacks to React.

Three ways to write one:

function add(a, b) { return a + b; }            // declaration, hoisted
const sub = function (a, b) { return a - b; }; // expression
const mul = (a, b) => a * b;                    // arrow, the modern default

Two non obvious things matter:

Arrow functions do not have their own this. They inherit it from where they were written. This is what you want most of the time, especially in callbacks.
Function declarations are hoisted to the top of their scope. You can call them above where they are written. Function expressions and arrows are not hoisted as values.

Closures, the secret superpower

A function "remembers" the variables that were in scope when it was created, even after that scope is gone. That is a closure.

function counter() {
  let count = 0;
  return () => ++count;
}

const next = counter();
next(); // 1
next(); // 2

The inner function still has access to count. Closures are how every JS pattern with private state works under the hood.

Decision 4: Objects, arrays, and the friendly modern syntax

const mood = {
  emoji: "😊",
  label: "happy",
  at:    new Date(),
  tags:  ["calm", "sunny"],
  nested: { weather: "clear" },
};

mood.label;         // "happy"
mood["label"];      // same thing
mood.nested?.weather; // "clear", optional chaining

const { emoji, label = "neutral" } = mood;        // destructuring with default
const { nested: { weather } } = mood;              // nested destructuring

const moodCopy = { ...mood, label: "joyful" };    // shallow copy with override
const moods = [mood, { ...mood, label: "okay" }];

const [first, ...rest] = moods;                    // rest in arrays
function greet(name, ...others) { /* others is an array */ }

The modern bits worth memorizing:

?. is optional chaining. a?.b returns undefined if a is null or undefined instead of throwing.
?? is nullish coalescing. value ?? "default" falls back only when value is null or undefined (unlike ||, which also falls back on 0 and "").
Spread ... copies things. Rest ... collects things. Same syntax, opposite meaning, context tells you which.

Decision 5: Equality, and the eternal `===`

There are two equality operators. Use one of them and forget the other exists.

1 == "1";   // true. Loose equality coerces types. Confusing.
1 === "1";  // false. Strict equality. The right answer.

Always use === and !==. The only honourable exception is value == null, which is a useful shortcut for "is null or undefined".

Other equality landmines:

NaN === NaN;          // false (yes, really)
Number.isNaN(NaN);    // true (the right way to check)
Object.is(NaN, NaN);  // true
0 === -0;             // true
Object.is(0, -0);     // false

Decision 6: Prototypes, and the classes built on top

JavaScript objects do not have classes underneath. They have a prototype chain. Every object has a hidden link to another object. When you ask for a property, JS walks the chain until it finds it or hits the end.

const cat = { meow() { return "meow"; } };
const mochi = Object.create(cat);
mochi.name = "Mochi";
mochi.meow(); // "meow", inherited

class syntax is just sugar over this:

class Mood {
  constructor(label) {
    this.label = label;
  }
  describe() {
    return `Feeling ${this.label}`;
  }
}

const m = new Mood("calm");
m.describe(); // "Feeling calm"

Modern classes also support private fields with #:

class Counter {
  #count = 0;
  inc() { this.#count++; }
  get value() { return this.#count; }
}

Use classes when you want a clean way to bundle state with methods. Use plain objects when you do not.

Decision 7: `this`, the most confusing word

this does not mean what it means in most languages. It depends on how the function is called, not where it was defined (except for arrow functions).

const obj = {
  label: "hi",
  say() { console.log(this.label); }
};

obj.say();             // "hi", this is obj
const f = obj.say;
f();                   // undefined or error in strict mode, this is not bound

Three ways to fix it:

Use an arrow function (inherits this from outside).
Bind explicitly: obj.say.bind(obj).
Call with the right form: obj.say() instead of pulling the function out.

The single most useful rule of thumb: inside a method, only use this directly. Inside a callback, use an arrow function or a closed over reference.

Decision 8: Async, the three eras

JavaScript runs on a single thread. To stay responsive, anything that takes time (network, disk, timers) is asynchronous. The way we wrote async code evolved through three eras.

Era 1: callbacks (legacy)

fs.readFile("mood.json", (err, data) => {
  if (err) return handle(err);
  // ...
});

Stack callbacks deep enough and you get "callback hell".

Era 2: Promises

A Promise is an object that represents a future value. It is in one of three states: pending, fulfilled, rejected.

fetch("/api/moods")
  .then((res) => res.json())
  .then((moods) => render(moods))
  .catch((err) => showError(err));

You can chain. You can Promise.all([p1, p2]) to run things in parallel. You can Promise.race, Promise.any, Promise.allSettled.

Era 3: async / await (the modern default)

Syntactic sugar over Promises, but reads top to bottom like normal code.

async function loadMoods() {
  try {
    const res   = await fetch("/api/moods");
    const moods = await res.json();
    render(moods);
  } catch (err) {
    showError(err);
  }
}

Rules:

An async function always returns a Promise, even if you return 5.
await pauses inside the async function until the Promise settles. It does not block other code.
await two things in sequence runs them in sequence. Use Promise.all to run them in parallel.

// sequential, slow
const a = await fetchA();
const b = await fetchB();

// parallel, fast
const [a, b] = await Promise.all([fetchA(), fetchB()]);

Decision 9: The event loop, the actual brain

Why does any of this work on a single thread? The event loop.

Roughly:

JS runs the code on the call stack until it is empty.
Async work (timers, network, I/O) is handed off to the host (browser or Node).
When the host is done, it puts a callback into a task queue.
The event loop pulls from the queue when the stack is empty and runs it.
Microtasks (Promise callbacks, queueMicrotask) run before the next task. They get priority.

Three consequences worth knowing:

A blocking loop (while (true) {}) freezes everything, including the page.
setTimeout(fn, 0) does not run "immediately". It runs after the current task, possibly after microtasks.
Awaiting a Promise that resolves with a Promise is fine. JS unwraps them for you.

Decision 10: Modules, the modern way to organize code

Modern JavaScript uses ES Modules (ESM). Every file is its own scope. You import what you need and export what you offer.

// mood.js
export function describe(m) { return `Feeling ${m.label}`; }
export const DEFAULT_MOOD = { label: "neutral" };
export default function MoodCard(props) { /* ... */ }

// app.js
import MoodCard, { describe, DEFAULT_MOOD } from "./mood.js";

A few rules:

One file, one module. Imports are static, the bundler can tree shake unused exports.
Top level await is allowed in modules. Useful for config loading.
Dynamic import when you only sometimes need a module: const m = await import("./heavy.js").

The old format you will still see in legacy Node code is CommonJS: const x = require("x"); module.exports = .... New code defaults to ESM.

Decision 11: Iterators, generators, and the for...of party

Anything that follows the iterator protocol can be looped.

for (const mood of moods) { /* arrays, sets, maps, strings */ }
for (const [key, value] of Object.entries(obj)) { /* objects */ }
for (const key in obj) { /* the keys, including prototype keys, prefer Object.keys */ }

Generators (functions with function*) let you yield values lazily, perfect for streams or infinite sequences.

function* range(start, end) {
  for (let i = start; i < end; i++) yield i;
}

for (const i of range(0, 5)) { /* 0, 1, 2, 3, 4 */ }

Most of the time you will not write generators. Most of the time you will use the iterator protocol indirectly through for...of, spread, and array methods.

Decision 12: Useful collections beyond array and object

Map for any kind of key (objects too), keeps insertion order, has .size.
Set for unique values. [...new Set(arr)] deduplicates an array.
WeakMap / WeakSet for memory friendly key references that allow garbage collection.

const seen = new Set();
moods.filter((m) => !seen.has(m.id) && seen.add(m.id));

When the keys are not strings or you need predictable iteration order, Map beats a plain object.

Decision 13: Errors, and how to handle them

try {
  riskyThing();
} catch (err) {
  if (err instanceof RangeError) { /* ... */ }
  if (err.code === "ENOENT")     { /* ... */ }
  throw err; // rethrow if you cannot handle
} finally {
  cleanup();
}

Modern best practices:

Throw Error objects, not strings. They carry a stack trace.
Subclass Error for app specific kinds: class NotFoundError extends Error {}.
Use Error cause: new Error("could not load", { cause: original }).
In async code, await inside try, otherwise the catch will not see the rejection.

Decision 14: A few modern goodies

Optional chaining (a?.b) and nullish coalescing (a ?? b).
Logical assignment (a ||= b, a ??= b, a &&= b).
structuredClone(obj) for a deep clone built into the platform. No more JSON.parse(JSON.stringify(...)).
Object.groupBy(arr, fn) for grouping arrays by a key.
Array.prototype.toSorted / toReversed / toSpliced / with for non mutating versions of the classics.
Promise.withResolvers() for cleaner manual Promise creation.
AbortController for cancelling fetches and other async work.
Top level await in modules.
BigInt for integers larger than Number.MAX_SAFE_INTEGER (about 9 quadrillion).

Decision 15: Tooling that you should know exists

In 2026, almost no real JavaScript project ships hand written, untranspiled, no bundler code. The modern stack:

Node.js runs JS on the server. Recent versions ship with a fetch, a test runner, and ESM as default.
Bun and Deno are alternative runtimes. Bun is fast and has a built in bundler. Deno has built in TypeScript and security permissions.
Vite is the bundler of choice for frontend apps. esbuild and SWC power most build tools under the hood.
TypeScript adds a static type layer over JavaScript. Almost every team uses it for non trivial apps.
Biome and ESLint lint your code. Prettier formats it.
Vitest is the modern test runner. Playwright does end to end tests.

You do not need to learn all of them on day one. Learn that they exist so you recognize the names.

A peek under the hood

What really happens when a browser runs JavaScript:

The HTML parser hits a <script> tag and hands the source to the JS engine (V8 in Chrome and Node, JavaScriptCore in Safari, SpiderMonkey in Firefox).
The engine parses the source into bytecode.
The bytecode runs in an interpreter while a JIT compiler watches for hot functions and optimizes them into machine code.
The runtime gives the engine access to host APIs (DOM, fetch, timers in the browser; fs, net in Node).
The event loop coordinates async work.
Memory is managed by a garbage collector that periodically frees objects nothing references anymore.

Two consequences for senior level work:

Functions get faster the more they run (warm up, then JIT). This is why microbenchmarks lie.
Holding references to big objects in closures or long lived structures leaks memory. WeakMap and breaking references explicitly help.

Tiny tips that will save you later

Default to const. Use let only when you actually reassign. Never use var.
Use === always. Two characters of safety for free.
Treat data as immutable when you can. Spread, slice, toSorted. Mutating shared objects is a footgun.
Use arrow functions for callbacks, regular methods for object methods.
Use async/await. Wrap parallel work in Promise.all.
Use ESM (import/export). Avoid CJS in new code.
structuredClone for deep copies. No more JSON tricks.
Use Map and Set when keys are not strings or uniqueness matters.
Throw real Error objects with cause.
Add TypeScript as soon as the project has more than two files. Future you will be grateful.
Run node --inspect or DevTools when debugging. console.log is not the only tool.

Wrapping up

So that is the whole story. We needed a small, friendly language for the browser, and we ended up with one that runs everywhere, with three decades of backwards compatible features piled on top of each other. We have variables (const, let), values (primitives and objects), functions as first class citizens, prototypes hidden under classes, asynchronous code that evolved from callbacks to async/await, and an event loop quietly orchestrating everything.

We learned which corners are sharp (==, var, this, NaN, mutation), which features are modern and beautiful (?., ??, modules, generators, structuredClone), and which tools sit around the language (Node, Bun, Vite, TypeScript) to make real apps shippable.

Once that map is in your head, every blog post, every framework, every "weird JS quirk" tweet starts to feel familiar. JavaScript stops being a haunted attic and starts being the most flexible, most ubiquitous tool in your belt.

Happy scripting, and may your this always be what you expect.