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
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 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 it | When the HTML is built | First visit | What goes stale |
|---|---|---|---|
| Single page application | In the browser, after the bundle runs | Slow. The page cannot exist until the bundle downloads. | The data, unless the page refetches. The page asks once and then waits. |
| Server side rendering | On the server, for each request | Fast. The browser gets a finished page and paints at once. | Nothing. Every visit is fresh, because the server builds it fresh. |
| Static site generation | Once, at deploy time | Fastest. 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.
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.
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.
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.
Not run yet.
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.
Not run yet.
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.
Not run yet.
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.
Not run yet.
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.
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.
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.
How many incidents the list renders. Every row is a node the browser has to lay out. A long list needs paging, not patience.
How long the Node API takes to answer. The browser cannot fix this hop. Only the server can.
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.
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.
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>
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
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.
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.
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.
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.
Three questions. No score is saved anywhere. This is just you against the material.
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.
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:
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.
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:
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.
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:
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.
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:
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.
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 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.
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.
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
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.
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.
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.
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.
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.
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.
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.