Platform Engineering · Lesson 40

Frontend for Platform Engineers: The Page Is Part of the System

I used to think the frontend was someone else's job. The API was mine. The page was theirs. Then a status page I owned went white for half the team after a deploy, and the API was fine the whole time. The page is part of the system. A slow bundle is a slow service, even when the API answers in 60 ms. This lesson builds one page, a team status page, from a blank file to a React component to a Node API, and it follows one visit through nine hops. HTML first, CSS second, JavaScript last. That order is the order the user feels.

Difficulty: Intermediate · Know this first: Lesson 16, Lesson F26, Lesson 38

What you will build

By the end of this lesson you will have built the team status page three ways. First, a static HTML and CSS page that lists open incidents. Second, a plain JavaScript page that fetches the list from a Node API you run yourself. Third, the same list as a React style component, with TypeScript types on the data. You will also know when the HTML should be built on the server, when it should be built at deploy time, and when the browser should build it, and you will have a bundle budget you can defend.

What you need: Node.js on your own machine and a text editor. Nothing in this lesson runs against a live cloud from this page. The Node parts run on this machine and their outputs are shown exactly as they ran. The React build step runs on your own machine, and it is marked that way. Your file paths will differ.

The story: one page, three ways to build it

The team needs a status page. One page. It lists the services, which ones have an open incident, and how long each incident has been open. It is the first page an engineer opens when a pager goes off, so it has to load fast and it has to be right.

There are three ways to build that page, and they differ in one question: when does the HTML get built.

Way to build itWhen the HTML is builtFirst visitWhat goes stale
Single page applicationIn the browser, after the bundle runsSlow. The page cannot exist until the bundle downloads.The data, unless the page refetches. The page asks once and then waits.
Server side renderingOn the server, for each requestFast. The browser gets a finished page and paints at once.Nothing. Every visit is fresh, because the server builds it fresh.
Static site generationOnce, at deploy timeFastest. The browser gets a finished page from a cache.The page, until the next deploy. A status page that changes every minute needs a rebuild on every change, or it lies.

A single page application builds the HTML in the browser. The server sends a nearly empty shell and a JavaScript bundle. The bundle runs, fetches the data, and builds the page. The first visit is slow, because the page cannot exist until the bundle downloads and runs. The second visit is fast, because the bundle is cached.

Server side rendering builds the HTML on the server, for each request. The browser gets a finished page and paints it at once. The first visit is fast. The server does the work on every request, so the server has to hold the load.

Static site generation builds the HTML once, at deploy time. The browser gets a finished page from a cache, and nobody builds anything per request. The first visit is the fastest of the three. The page is only as fresh as the last deploy, so a status page that changes every minute needs a rebuild on every change, or it lies.

The lesson follows one first visit, server side rendered, through nine hops. The simulator lets you change the bundle, the rows, the API, and the images, and watch the total move.

Do this now, before the hops

Open the status page you use at work, or any dashboard you open every day. Open the browser tools, reload, and read the waterfall. Find the HTML, the CSS, and the JavaScript bundle, and write down the three sizes. The biggest file is the hop to watch. If the bundle is over 500 KB, you have already found the first fix in this lesson.

Run it as:

When it breaks, I check

One thing to remember

Four paths, one family

The diagram above follows one visit to the status page. These four paths are the same idea drawn four ways. One visit, finished. One visit, stopped by a bundle that never arrives. One byte trail, hop by hop. One return visit, mostly cached. Run each path. One run takes 7.2 seconds across the path, so you can watch each hop light up in turn.

The return rule: the green dot only starts moving after the orange dot reaches the data hop. A return with no request is a lie. The diagram never draws one. The failure replay at the end of Run all four shows the other side of the rule. Run it and watch the orange dot stop at the bundle and never come back.

Path 1: the first visit

Byte trail: skipped

One visit walks the page from the story. HTML shell, CSS, bundle, React, Node API, and the data hop. The server built the shell, the bundle costs 120 ms, and the data renders the list. The answer starts back at the data hop.

Client0 ms
HTML shell18 ms
CSS paints22 ms
JS bundle120 ms
React renders45 ms
Node API60 ms
Data renders35 ms

Not run yet.

Path 2: the bundle that never finishes

Data renders: skipped

The same visit, after a bad deploy. The bundle file returns 404. The shell paints, the CSS paints, and then nothing. React never runs, the API is never asked, and the data hop is never reached. The page stays a shell with a shape and no list.

Client0 ms
HTML shell18 ms
CSS paints22 ms
JS bundle404
React rendersskipped

Not run yet.

Path 3: the byte trail

React renders: skipped

The same visit, weighed hop by hop at the simulator defaults: 450 KB bundle, 100 rows, 8 images. The trail adds up to 848 KB. The bundle is the big line. The API answer is the smallest line that matters, because it is the only one that carries the truth.

Client0 KB
HTML shell12 KB
CSS paints48 KB
JS bundle450 KB
Images load320 KB
API JSON18 KB

Not run yet.

Path 4: the return visit

Byte trail: skipped

The same visit the next day. The shell revalidates in 2 ms. The CSS, the bundle, and the images come from the cache and cost 0 ms. React still renders, the API still answers, and the data still renders. The cache saved 182 ms, and the data still travelled fresh.

Client0 ms
HTML shell2 ms
CSS paintscached 0 ms
JS bundlecached 0 ms
React renders45 ms
Node API60 ms
Data renders35 ms

Not run yet.

Where the time goes

Every hop charges rent in milliseconds. The bar below is a worked example for one visit to the status page, not a measurement from a live system, but the shape is honest. The bundle hop is the big line. The API hop is the honest line. At the simulator defaults the total is 334 ms on a first visit. Move a simulator slider and watch the bundle hop and the render hops move with it. Switch the scenario and watch the cached hops drop to zero, or the bundle hop grow to 390 ms.

Bundle, rows, API, images: move the sliders and watch the page

The budget bar above shows three fixed stories. This simulator lets you write your own. It answers the trade-off at the heart of this lesson: the bundle and the rows are yours to control, the API is the server's, and the images are decoration you can shrink. You set how big the bundle is, how many rows the list renders, how slow the API is, and how many images the page carries. Move a slider and watch the bundle hop, the render hops, and the budget total change. The numbers are a teaching example, built from the formulas below, not live measurements. The shape is the lesson: the bundle is the hop you control, and it is the hop that grows when nobody watches it.

450 KB

How big the bundle is. Every library you add lives here. A status page has no business carrying a chart library and an admin panel.

100 rows

How many incidents the list renders. Every row is a node the browser has to lay out. A long list needs paging, not patience.

60 ms

How long the Node API takes to answer. The browser cannot fix this hop. Only the server can.

8 images

How many images the page loads. The icons beside each row. Decoration, not the answer, and it loads last on purpose.

Try this: (1) At the defaults, 450 KB bundle, 100 rows, 60 ms API, 8 images, the bundle hop is 120 ms, the React hop is 45 ms, the API hop is 60 ms, the data hop is 35 ms, and the images hop is 24 ms. The budget total is 334 ms, inside the 400 ms budget. (2) Drop to 100 KB bundle, 10 rows, 20 ms API, 0 images. The bundle hop falls to 50 ms, the React hop to 27 ms, the data hop to 17 ms, and the images hop to 8 ms. The budget total is 172 ms. The page is fast because every hop is small, not because one hop is fast. (3) Push to 2,000 KB bundle, 500 rows, 300 ms API, 40 images. The bundle hop grows to 430 ms, the React hop to 125 ms, the API hop to 300 ms, the data hop to 115 ms, and the images hop to 88 ms. The budget total is 1,108 ms. From the defaults, the big page waits 774 ms longer, and most of it is the bundle and the API. That is the trade, priced.

Formulas, in plain terms. Bundle hop = 30 ms plus 0.2 ms per kilobyte of bundle. React hop = 25 ms plus 0.2 ms per row. Data hop = 15 ms plus 0.2 ms per row. API hop = the slider value. Images hop = 8 ms plus 2 ms per image. Budget total = 0 ms plus 18 ms of HTML plus 22 ms of CSS plus the bundle hop plus the React hop plus the API hop plus the data hop plus the images hop plus 10 ms to be ready. The simulator moves the five hops it controls. The HTML, CSS, and ready hops stay fixed.

Lab: build the status page yourself

Do this now, on your own machine. You will write the static page, run the JavaScript basics, add TypeScript types, serve it from a Node API, and render the same list as a React style component. The Node parts run on this machine and their outputs are shown exactly as they ran. The React build step runs on your own machine, and it is marked that way. Your file paths will differ.

Step 0: the static page

Save this file as dashboard.html and open it in a browser. The page says "Loading incidents." and the list stays empty, because there is no API yet. That is the lesson in one screen: HTML alone cannot fetch data.

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Team status</title>
<style>
  body { font-family: system-ui, sans-serif; margin: 2rem; color: #1a1a1a; }
  h1 { font-size: 1.4rem; }
  .open { color: #a02c22; font-weight: 700; }
  .closed { color: #2e6b3e; }
  li { margin: 0.4rem 0; }
</style>
</head>
<body>
<h1>Team status</h1>
<p id="summary">Loading incidents.</p>
<ul id="list"></ul>
<script>
  // The browser asks the Node API for JSON, then builds the list.
  // No framework. The fetch, the loop, and the DOM write are the app.
  fetch("/api/incidents")
    .then((r) => r.json())
    .then((incidents) => {
      const open = incidents.filter((i) => i.status === "open");
      document.getElementById("summary").textContent =
        open.length + " open incident" + (open.length === 1 ? "" : "s") + ".";
      document.getElementById("list").innerHTML = incidents
        .map((i) => "<li class=\"" + i.status + "\">" + i.service + " " + i.status + ", " + i.minutes + " min</li>")
        .join("");
    });
</script>
</body>
</html>

Step 1: JavaScript basics

Save this file as hello.js and run it with node hello.js. One array, three operations. This is the whole language in miniature: a value, a function, and a list you can filter and reshape.

// hello.js: JavaScript basics, run with: node hello.js
// One array, three operations. This is the whole language in miniature:
// a value, a function, and a list you can filter and reshape.

const incidents = [
  { id: 1, service: "deploy", status: "open", minutes: 42 },
  { id: 2, service: "cache", status: "closed", minutes: 9 },
  { id: 3, service: "queue", status: "open", minutes: 17 },
];

const open = incidents.filter((i) => i.status === "open");
console.log("open incidents:", open.length);

const names = open.map((i) => i.service);
console.log("open services:", names.join(", "));

const total = open.reduce((sum, i) => sum + i.minutes, 0);
console.log("open minutes total:", total);

function oldest(list) {
  return list.reduce((a, b) => (a.minutes > b.minutes ? a : b));
}
console.log("oldest open incident:", oldest(open).service, "at", oldest(open).minutes, "minutes");

The output, exactly as it ran:

open incidents: 2
open services: deploy, queue
open minutes total: 59
oldest open incident: deploy at 42 minutes

Step 2: TypeScript types

Save this file as types.ts. Compile it with npx tsc types.ts --target es2020 --module commonjs, then run it with node types.js. The types are checked at compile time and erased at run time. If a field is missing or the wrong kind, tsc refuses before node runs.

// types.ts: the same incident list, with TypeScript types.
// Compile with: npx tsc types.ts --target es2020 --module commonjs
// Then run with: node types.js
// The types are checked at compile time and erased at run time.
// If a field is missing or the wrong kind, tsc refuses before node runs.

type Status = "open" | "closed";

interface Incident {
  id: number;
  service: string;
  status: Status;
  minutes: number;
}

const incidents: Incident[] = [
  { id: 1, service: "deploy", status: "open", minutes: 42 },
  { id: 2, service: "cache", status: "closed", minutes: 9 },
  { id: 3, service: "queue", status: "open", minutes: 17 },
];

function openIncidents(list: Incident[]): Incident[] {
  return list.filter((i) => i.status === "open");
}

function oldest(list: Incident[]): Incident {
  return list.reduce((a, b) => (a.minutes > b.minutes ? a : b));
}

const openList = openIncidents(incidents);
console.log("open incidents:", openList.length);
console.log("oldest open incident:", oldest(openList).service, "at", oldest(openList).minutes, "minutes");

The output, exactly as it ran:

open incidents: 2
oldest open incident: deploy at 42 minutes

Now break a type on purpose. Change one minutes value to a string and run tsc again. tsc refuses before node runs. That refusal is the whole point of TypeScript.

Step 3: the Node API

Save this file as server.js, in the same folder as dashboard.html, and run it with node server.js. It serves the dashboard page at / and the incident JSON at /api/incidents. The script starts the server, asks it for the JSON itself, prints the answer, and stops.

// server.js: a Node.js API with no dependencies.
// Run with: node server.js
// It serves the dashboard page at / and incident JSON at /api/incidents.
// The script starts the server, asks it for the JSON itself, prints the
// answer, and stops. That self-check is the run output below.

const http = require("http");
const fs = require("fs");
const path = require("path");

const incidents = [
  { id: 1, service: "deploy", status: "open", minutes: 42 },
  { id: 2, service: "cache", status: "closed", minutes: 9 },
  { id: 3, service: "queue", status: "open", minutes: 17 },
];

const page = fs.readFileSync(path.join(__dirname, "dashboard.html"), "utf8");

const server = http.createServer((req, res) => {
  if (req.url === "/api/incidents") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(incidents));
    return;
  }
  res.writeHead(200, { "Content-Type": "text/html" });
  res.end(page);
});

server.listen(0, "127.0.0.1", () => {
  const port = server.address().port;
  fetch("http://127.0.0.1:" + port + "/api/incidents")
    .then((r) => r.json())
    .then((data) => {
      console.log("GET /api/incidents ->", JSON.stringify(data));
      console.log("open incidents:", data.filter((i) => i.status === "open").length);
      console.log("page bytes:", page.length);
      server.close();
    });
});

The output, exactly as it ran:

GET /api/incidents -> [{"id":1,"service":"deploy","status":"open","minutes":42},{"id":2,"service":"cache","status":"closed","minutes":9},{"id":3,"service":"queue","status":"open","minutes":17}]
open incidents: 2
page bytes: 1066

Then open the page in a browser at the printed address. The list fills in. The fetch, the loop, and the DOM write are the app.

Step 4: the React idea, then the real React

Save this file as render.js and run it with node render.js. React is a function from data to HTML: a component takes props and returns markup. This file does the same job with a plain function, so you can run it here and see the output. Real React adds a build step and a reconciler that updates only what changed. The idea is the same.

// render.js: the React idea in plain Node, no dependency.
// React is a function from data to HTML: a component takes props and
// returns markup. This file does the same job with a plain function,
// so you can run it here and see the output. Real React adds a build
// step and a reconciler that updates only what changed. The idea is
// the same. Run with: node render.js

function IncidentRow(props) {
  return "<li class=\"" + props.status + "\">" +
    props.service + " " + props.status + ", " + props.minutes + " min</li>";
}

function IncidentList(props) {
  const open = props.incidents.filter((i) => i.status === "open");
  const rows = props.incidents.map(IncidentRow).join("");
  return "<h1>Team status</h1>" +
    "<p>" + open.length + " open incidents.</p>" +
    "<ul>" + rows + "</ul>";
}

const incidents = [
  { id: 1, service: "deploy", status: "open", minutes: 42 },
  { id: 2, service: "cache", status: "closed", minutes: 9 },
  { id: 3, service: "queue", status: "open", minutes: 17 },
];

console.log(IncidentList({ incidents }));

The output, exactly as it ran:

<h1>Team status</h1><p>2 open incidents.</p><ul><li class="open">deploy open, 42 min</li><li class="closed">cache closed, 9 min</li><li class="open">queue open, 17 min</li></ul>

Then, on your own machine, build the real React version. This step runs on your machine, and its output is yours, not shown here. Run npm create vite, pick React and TypeScript, move IncidentList into a component file, and start the dev server. The component you write is the same function from data to HTML that render.js shows. The build step is the difference: Vite bundles your component, splits the code, and hashes the filename, which is the cache rule from Go deeper doing its job.

Step 5: check the page

Run node check_page.js in the same folder. It reads dashboard.html and counts the parts the browser needs: the list mount point, the summary line, the fetch call, and the style and script blocks. The output, exactly as it ran, is six PASS lines and "dashboard.html: all checks pass". If any line says FAIL, the page is broken in exactly the place the line names.

Check yourself

Three questions. No score is saved anywhere. This is just you against the material.

Basic to master

Building a frontend is not one skill. It is four levels of the same job, and every team I have worked with sits on one of them. The levels are not about how many frameworks you can name. They are about whether the page stays fast and true when real engineers depend on it. Read them in order. Each level fixes the failure that hurt the most at the level below it.

Basic · One static page, built by hand

At the basic level, you write the HTML and the CSS, and you open it in a browser. The page lists three incidents you typed in by hand. It loads fast, because there is almost nothing to load. The failure that ends this level is the fourth incident. A page with the data typed in cannot change, and a status page that cannot change is a poster, not a tool.

Types:

  • HTML: the structure and content of the page.
  • CSS: layout, colours, and responsive rules for different screens.
  • Static hosting: files served from a CDN or object storage with no server code.
  • Browser developer tools: the network tab and the console.

Uses: Runbooks, simple status pages, and internal documentation that rarely changes.

Scale and failure: Static pages scale almost without limit behind a CDN, which is why status pages are often static. The failure is staleness: a page that must be edited by hand is wrong as soon as the situation changes.

Trade-off: Static is fast, cheap, and survives outages of everything else, and it cannot show live data without a separate fetch.

Do this: run step 0 of the lab. Open dashboard.html and read the list. Then change one incident by hand and reload. The edit is the whole deploy.

Try it: Basic

I type three incidents into my page by hand. What breaks first when a fourth incident happens?

Now do it: Run step 0 of the lab. Open dashboard.html, read the list, change one incident by hand, and reload. The edit is the whole deploy.

Intermediate · The page fetches its data

At the intermediate level, you run the Node API, and the page asks it for the list. You add TypeScript types to the incident, so a missing field fails at compile time instead of at 2 AM. The failure that ends this level is the stale list. The page asks once and never asks again, and an incident that clears stays open on the screen.

Types:

  • fetch and JSON APIs: the page asks a server for data.
  • TypeScript types for API responses: missing fields fail at build time.
  • Polling versus server-sent events versus WebSockets for updates.
  • CORS: the browser rule that decides which origins may call your API.

Uses: Dashboards and internal tools that show live data from platform APIs.

Scale and failure: A page that polls every second, open in five hundred engineers' browsers during an incident, is 500 requests a second to your API at exactly the worst time. Poll intervals, caching headers, and backoff are platform concerns, not frontend details.

Trade-off: Polling is simple and wasteful; server-sent events push updates efficiently and hold a connection per open page. Choose by how many viewers and how fresh the data must be.

Do this: run steps 1 to 3 of the lab. Then change the API data while the page is open and watch the page not change. That stillness is the bug.

Try it: Intermediate

My page asks the API once and never asks again. An incident clears. What do I see on the screen?

Now do it: Run steps 1 to 3 of the lab. Change the API data while the page is open and watch the page not change. That stillness is the bug.

Advanced · React, and the rendering choice

At the advanced level, you build the list as a component, and you choose where the HTML gets built: server side rendering for the first visit, static generation for a page that rarely changes, a single page application for a page the engineer keeps open. You set a bundle budget, 200 KB for this page, and the build fails when the bundle crosses it.

Types:

  • Rendering modes: server-side rendering, static generation, and single-page applications.
  • Components with state, such as React, rendering lists from data.
  • Bundle budgets enforced at build time.
  • Core Web Vitals: largest contentful paint, interaction to next paint, cumulative layout shift.

Uses: Internal developer portals and customer-facing consoles where load time and correctness both matter.

Scale and failure: Every dependency added to the bundle is downloaded by every visitor; a 2 MB bundle on a slow corporate VPN turns a dashboard into a minute-long wait. Budgets in CI stop the growth before users feel it.

Trade-off: Single-page applications feel fast once loaded and are slow to load first; server rendering shows content sooner and needs a server. Static generation is fastest and only fits data that changes rarely.

Do this: run step 4 of the lab. Then add a chart library to the bundle and watch the budget fail. The failure is the feature working.

Try it: Advanced

My bundle budget is 200 KB. I add a chart library and the build fails. What failed?

Now do it: Run step 4 of the lab. Add a chart library to the bundle and watch the budget fail. The failure is the feature working.

Master · The page as a product

At the master level, the performance budget runs in CI. The cache headers are code, not a setting someone clicked once. An error boundary catches a broken component and shows the rest of the page instead of a white screen. The page refetches on focus and on a timer, and it shows the age of the data it displays, so a stale list says it is stale. The microfrontend boundary is written down: the admin panel is a separate app with its own bundle, and it never ships on the status page.

Types:

  • Performance budgets and Lighthouse runs in CI.
  • Cache-Control headers as code: immutable hashed assets, short-lived HTML.
  • Error boundaries: a broken component degrades instead of blanking the page.
  • Microfrontends: separately built and deployed parts of a large UI.

Uses: Platform portals that many teams use daily, where a broken deploy blocks everyone's work.

Scale and failure: With many teams contributing, the frontend needs the same discipline as a backend: ownership per part, budgets per part, and a rollback path. Microfrontends give teams independence and cost duplicate dependencies and harder consistency.

Trade-off: A single application is consistent and fast and couples every team's release. Microfrontends decouple teams and add bundle weight and integration work. Split only when release coupling is a real problem.

Do this: write the budget into the build, one line, and break it on purpose. Then write the error boundary around the list component and throw inside it. The page must show the rest of the page and a short error, not a white screen.

Try it: Master

A component breaks on my status page. What should the reader see instead of a white screen?

Now do it: Write the budget into the build, one line, and break it on purpose. Then write the error boundary around the list component and throw inside it. The page must show the rest of the page and a short error, not a white screen.

Go deeper

SSR, SPA, and SSG are one question

The three ways to build a page differ in one question: when does the HTML get built. A single page application builds it in the browser, after the bundle. The first visit is slow, later visits are fast, and the page goes stale unless it refetches. Server side rendering builds it on the server, per request. The first visit is fast, the server holds the load, and the page is fresh on every visit. Static site generation builds it once, at deploy time. The first visit is the fastest, nobody builds per request, and the page is only as fresh as the last deploy. A status page that changes every minute is a bad fit for static generation unless a rebuild runs on every change. A marketing page that changes once a month is a bad fit for server side rendering, because the server rebuilds a page that never changes.

React is the framework, not the only framework

React is the framework this lesson builds with. Vue and Angular are the other two big frameworks you will meet on real teams, and the ideas transfer: components, props, and a render from data to HTML. Vue is the gentlest start of the three. Angular is the heaviest, with more built in and more to learn. Pick React first, because the jobs and the examples are the most common, and learn the others by reading their component code, not by rebuilding this page three times. A single page application, server side rendering, and static site generation are rendering choices, not framework choices. Any of the three frameworks can do any of the three, and the question stays the same: when does the HTML get built.

Hydration is the tax on server side rendering

The server sends finished HTML, and then the JavaScript runs and attaches the handlers. Between the paint and the hydration, the page looks ready and is not. A button that does nothing for a second is a hydration gap. React 18 streams the HTML and hydrates in pieces, so the list can be interactive while the chart below it is still loading. The gap does not go away. It gets smaller, and it gets smaller in the order that matters.

Cache headers are the deploy

A bundle file with a content hash gets a long cache header, one year, because the name changes when the content changes. The HTML shell gets a short header, or no cache at all, because the shell names the bundle. If the HTML is cached for an hour and the bundle changes, the old shell asks for the old bundle, and the old bundle is gone. That is the incident in this lesson. The rule is short: cache the files with hashes for a long time, and do not cache the file that names them.

Cache-Control: public, max-age=31536000, immutable   # bundle.a3f9c1.js, name has a hash
Cache-Control: no-cache                                # index.html, the shell names the bundle

Microfrontends are a boundary decision, not a framework decision

One team owns the status page. Another team owns the admin panel. Each ships its own bundle, on its own deploy, and the shell loads them together. The win is independent deploys. The cost is two bundles, two frameworks if the teams disagree, and a shared design that drifts. A microfrontend is right when the teams deploy on different days. It is wrong when one team owns both pages and just wants to feel modern.

What changes at 10x and 100x

At 10x the rows, the list needs paging, and the API needs a page size, because 500 rows is 500 nodes and the browser lays out all of them. At 10x the engineers, the API needs a cache, because 5,000 browsers asking every 30 seconds is a load the Node process feels. At 100x, the status page is a product with an owner, a budget in CI, and a deploy pipeline of its own. The page does not change. The number of people who depend on it does.

Further reading

The React documentation, on rendering and hydration. The Vite getting started guide, for the build step in the lab. web.dev on performance, for resource loading and caching. All three are the reference, not the lesson. The lesson is the page you built.

One time it broke

What broke

A deploy shipped a new bundle under the same filename. The HTML shell named bundle.js. The CDN had bundle.js cached from the last deploy. Half the team got the new shell and the old bundle. The new shell called a function the old bundle did not have. The page went white. The API was fine. The server was fine. The page was white, and the status page is the page you open when something breaks.

Timeline

  • 14:00Deploy ships. The new bundle has the same filename as the old one.
  • 14:02The first report: the status page is white.
  • 14:10The dashboard shows the API healthy and the server healthy. I blame the browser.
  • 14:25I open the page myself. It loads fine, because my browser had never cached the old bundle.
  • 14:40A teammate sends a screenshot. The console says a function is not defined.
  • 14:50I compare the shell and the bundle. The shell is new. The bundle is old.
  • 15:00I rename the bundle with a content hash and redeploy. The page comes back.

What changed after

Two rules. First, every bundle file carries a content hash in its name, and the HTML names the hash. A new bundle is a new file, and the cache cannot serve the old one by mistake. Second, the deploy checks the shell and the bundle together. A shell that names a bundle that does not exist fails the deploy, before it reaches anyone.

If you remember nothing else

Design exercise

Design the status page for 50 services and 5,000 engineers. The page lists every open incident, updates every 30 seconds, and has to load in under 400 ms on a first visit. The admin panel lives on the same site. The team deploys the page twice a day.

Clarifying questions to ask

  • How many incidents are open at once, on a bad day?
  • How big is the incident payload, and which fields does the list actually show?
  • Who opens the admin panel, and how often?
  • What happens when the API is down: does the page show the last list, or does it show nothing?
  • What is the first visit budget, and who owns it when it breaks?

Worked approach

Start with the numbers. Fifty services, ten open incidents on a bad day. Ten rows is a short list, and the render is cheap. The payload is 18 KB for 100 rows, so ten rows is under 2 KB. The API is not the problem. The bundle is. Set the bundle budget at 200 KB for the status page, and keep the admin panel in its own bundle, lazy loaded. The admin panel is a separate app with its own deploy. The page is server side rendered, so the first visit paints fast, and it refetches every 30 seconds and when the tab comes back into focus. The page shows the age of the data, so a list that is two minutes old says it is two minutes old. The images are icons, lazy loaded, and the total page weight stays under 300 KB.

Then the hop math. The first visit total is the hop math from this lesson: 18 ms of HTML, 22 ms of CSS, 50 ms of bundle at 100 KB, 27 ms of React for ten rows, 60 ms of API, 17 ms of data, 8 ms of images, 10 ms to be ready. That is 212 ms, inside the 400 ms budget, with room for a bad day.

Trade-offs to name. Server side rendering against static generation. Static is faster and cheaper, but the page goes stale between deploys, and this page changes every minute. The server holds the load on every visit, and that load is the price of fresh data. The 30 second refetch against a push connection. A push connection is fresher and costs a connection per browser. A 30 second poll is simpler and is stale for up to 30 seconds. The page shows the data age, so the staleness is honest instead of hidden. The separate admin bundle against one bundle. One bundle is simpler to build. Two bundles keep the status page fast, and the admin panel deploys on its own day.

Saved in this browser, so the Lessons index can show your progress across the course.

Next in this series · Lesson 41
Pick Two: The CAP Trade

Three copies of the same data should agree. Most days they do. Then the network between them is cut, and I have to choose. I can keep taking writes and let the copies disagree, or I can keep the copies in agreement and refuse…

Go to Lesson 41 →

Or browse the full course from the Lessons index.