The budget came before the code

Before the redesign, this site was a cautionary tale I built myself: a full-viewport canvas glitch animation behind the hero, particle effects on every section title, animated SVG borders around every project card, ~16 MB of raw PNG screenshots, and a * { transition } CSS rule taxing every element on the page. The git history contains a commit called fix mobile lags. It did not fix the mobile lags.

The rebuild started with a budget, not a design:

The JavaScript number deserves honesty: on Next.js 15 with the App Router, the framework baseline — React, the router, hydration — is roughly 100 kB gzipped before you write a line of your own code. A hand-written static page could be 10 kB; if I ever migrate this site to zero-hydration HTML, that becomes the budget. Until then, the honest budget is "framework floor plus almost nothing", and the enforcement is automated: the build fails in CI if a route's first-load JS grows past the ceiling.

What actually loads

Reload this page with the Network tab open and disable cache. You will see, in order:

1. The HTML document. Statically exported at build time — there is no server rendering on demand, no API calls, no waiting. Everything you read arrived in the first response, which also means the page works with JavaScript disabled.
2. Two font families. Geist Sans and Geist Mono, subset to Latin and self-hosted as woff2, with size-adjusted fallback metrics generated at build time. No round-trip to a font CDN, and no layout shift when they arrive. (The full font strategy has its own article.)
3. One stylesheet. Tailwind compiles to a single small CSS file containing only the classes this site actually uses.
4. The JavaScript chunks — all async. None of them block rendering. The page paints before React hydrates, and the only interactive components on the home page are small: a theme toggle, a scroll-spy for the sidebar navigation, a copy-email button, and a ~3 kB Web Vitals reporter.
5. Images, lazily. Project screenshots are 800-pixel WebP files of 15–55 kB each, loaded only as you scroll to them, each with explicit dimensions so nothing shifts.

What you will not see is often the more important list.

What this site refuses to ship

Every item below was either in the old version of this site or is standard issue on portfolio sites, and each one was cut deliberately:

• No canvas or WebGL. The old glitch-effect hero ran a full-viewport canvas loop from the moment the page opened until you closed the tab. Decorative animation on this site is now CSS only, runs on the compositor, and respects prefers-reduced-motion.
• No animation library. The previous build shipped framer-motion — around 40 kB gzipped — to animate a decorative beam and a toggle button. Everything it did is now CSS transitions and scroll-driven animations, which cost zero JavaScript.
• No third-party requests at all. No analytics script, no tag manager, no consent banner (nothing to consent to — there are no cookies), no font CDN, no screenshot service. Open the Network tab's domain column: every request comes from this origin. The only telemetry is a tiny beacon that reports anonymous Core Web Vitals — LCP, INP, CLS — so I can see the field data I write about.
• No hero video, no icon font, no CSS framework runtime. The icons are a handful of inline SVGs.

The pattern behind the list: on the modern web, most performance work is subtraction. The fastest request is the one you don't make.

The three decisions that mattered most

Everything else was detail; these three choices did the heavy lifting.

Static export over server rendering. The site is prebuilt to plain HTML at deploy time (output: "export") and served from a CDN. Time-to-first-byte is a cache hit, not a function invocation. This forecloses server features — and for a portfolio, that constraint is a gift: it makes slow architecture impossible.

Images resized at build time. Next.js's image optimizer doesn't run under static export, so a small sharp script resizes and re-encodes every screenshot to WebP at the exact display size before the build. The six project screenshots went from 16.2 MB of PNG to 167 kB total — a 99% reduction, and the single biggest fix in this rebuild.

Deleting instead of optimizing. The old effect stack wasn't slow because it was badly written; it was slow because it existed. No amount of useMemo makes a permanent full-screen canvas loop cheap. Cutting it improved every metric at once — JavaScript size, main-thread time, battery, INP — and, honestly, the design too.

Lab numbers vs. what you experience

The numbers above are lab numbers: measured on a throttled connection with a cold cache, the way Lighthouse or WebPageTest would. Your load just now was probably faster — warm CDN, real broadband, maybe a repeat visit served from the browser's back/forward cache in ~0 ms.

Field data — what real visitors experience at the 75th percentile — is the truth that matters, and it's collected here by the Web Vitals beacon mentioned above. As it accumulates, the numbers on the /perf page come from real visits, not my machine. That page also carries the current budget, what the CI enforcement looks like, and a changelog of every performance regression I find in my own site, because publishing your own regressions is more convincing than publishing your wins.

The JavaScript side of this story — where the 68 kB actually came from — is broken down in Your Next.js Bundle Is Lying to You.

Reproduce this audit on any site in 15 minutes

1. Open DevTools → Network. Check "Disable cache", set throttling to "Fast 4G", reload. Count the requests before first paint — anything render-blocking shows up before the first pixel.
2. Find the LCP element: Performance tab → record a reload → click the LCP marker. Ask: when did the browser learn about this resource? Late discovery, not slow download, is the usual LCP killer.
3. Sort Network by size. Anything over 100 kB must justify itself.
4. Filter by domain. Every third-party origin is a negotiation someone should have had.
5. Run Lighthouse twice and keep the second run (the first is polluted by extension noise more often than people think).

If you do this to your own site and find something interesting, email me — the best future article on this site might be your waterfall.

This isn't a React hit piece. It's a map of where the milliseconds go and the specific tools — most of them shipped by React itself — that get them back.

What INP actually measures

INP takes (roughly) the worst interaction of a user's visit and measures input to next painted frame, in three phases:

1. Input delay — the event happened, but the main thread was busy finishing something else. Your handler hasn't even started.
2. Processing — your event handlers run. In React: the state update, the re-render of every affected component, the reconciliation, the commit.
3. Presentation delay — style, layout, paint, composite for the resulting frame.

Under 200 ms is good; over 500 ms is poor. If you want to feel the thresholds instead of reading them, I built a 30-second demo on this site's lab page — it blocks the main thread for a duration you choose and shows you the measured gap. 200 ms feels like a hesitation. 1000 ms feels broken.

The trap in the definition: the click handler you wrote is only phase 2. Profile just your handler and you'll miss the input delay caused by that analytics script chewing the thread, and the 300 ms render your setState scheduled.

Why React concentrates the damage

React's model is: state changed → re-render the affected subtree → commit, synchronously by default. Three properties of real codebases turn that into long tasks:

• Renders cascade wider than intended. A context value changes and every consumer re-renders; a parent re-creates a callback and memoized children bail out of bailing out. The render tree is bigger than the mental model of it.
• The expensive path is the common path. A controlled input re-renders on every keystroke. Wire it to a 2,000-row filtered list without care, and typing becomes fifteen 250 ms tasks in a row — INP samples every one of them.
• It all happens at input time. Server components, SSR, and streaming moved loading work off the client, but interactions are still, definitionally, client work. INP is the metric your architecture migration didn't fix.

Reading the trace

One recorded Performance-panel trace of a slow click tells you which phase to attack. The signature of each:

• A long yellow task before your handler's flame: input delay — something else (hydration, a third-party, a previous render) was hogging the thread. Your handler is innocent; the page's background work is guilty.
• A wide onClick frame with your code in it: processing, your logic — you're doing real computation in the handler. Move it off the interaction (worker, deferral, memoized ahead of time).
• A wide "Commit" / render flame after your code returns: processing, React's render — the state update redrew too much. This is the usual suspect, and the whole next section.
• Purple layout blocks after commit: presentation — you invalidated layout for thousands of nodes, or wrote layout-triggering styles from JS.

The fix ladder

Ordered by effort-to-impact; stop at the first rung that gets you under 200 ms.

1. Render less. Push state down to the smallest component that needs it; split contexts so consumers subscribe to what they actually read; memo the expensive subtrees the update shouldn't touch. Boring, mechanical, and it's rung one because it's usually the whole fix.

2. Split urgent from deferrable. This is the rung React built specifically for INP:

const [query, setQuery] = useState("");
const deferredQuery = useDeferredValue(query);
// input renders with `query` — urgent, every keystroke
// the 2,000-row list renders with `deferredQuery` — interruptible, lags harmlessly

useTransition is the same idea for updates you trigger (tab switches, filters): the click paints now, the heavy new tree renders concurrently and can be interrupted by the next input. This is concurrent rendering doing exactly what it was designed for — the frame after input stays cheap, which is the frame INP measures.

3. Yield inside long work. For genuinely long computation that must run on interaction, break it up so input can interleave: scheduler.yield() (or a setTimeout(0) chunk loop where unsupported) between batches. A 600 ms task becomes twelve 50 ms tasks, and the user's next click slots in between.

4. Leave the main thread. Search indexes, parsing, diffing — Worker + transferable data. The main thread's only job during an interaction is painting the response to it.

5. Leave React out of it. Hover states, open/close toggles, animations: CSS handles them at compositor priority with zero render cycles. The fastest re-render is the one that never happens — sometimes the senior fix is admitting the interaction never needed state.

Measure like you mean it

Lab clicks on a dev machine won't reproduce what a mid-range Android feels. Two habits close the gap:

• 4–6× CPU throttling in the Performance panel for every interaction you profile. This site's lab demo at 200 ms feels fine unthrottled — throttle and watch it cross into "poor".
• Field attribution. The web-vitals library's attribution build tells you which element and which phase produced each bad INP sample in production. One week of field attribution beats a month of guessing which interaction to fix. (This site beacons its INP field data — the plain build for now, attribution upgrade queued — details on /perf.)

The one-sentence version: INP is where React's costs concentrate, React 18+ shipped the escape hatches, and the trace tells you which one you need. The rest is discipline.

The only number that matters (and what it hides)

When next build finishes, it prints a table. The number to read is First Load JS — the gzipped JavaScript a new visitor downloads to render a route. Ignore the per-route "Size" column until you understand what's shared.

Route (app)                    Size    First Load JS
┌ ○ /                        1.88 kB       107 kB
+ First Load JS shared by all              102 kB

Three things this table hides:

1. The floor. On Next.js 15 with the App Router, the shared baseline — React, the router, hydration runtime — is ~100 kB gzipped before you write a line of code. Your leverage is everything above the floor. When this site's home route reads 107 kB, the honest reading is: framework 102, me 5.
2. What "shared" means. A chunk used by every route lands in the shared row. One heavy import in your root layout.tsx taxes every page on the site. The layout is the most expensive place to put code, and the place people audit least.
3. It's an estimate. The table is computed at build time. What browsers actually download can differ (the noModule polyfill chunk, for example, appears in the HTML but is never fetched by modern browsers). When I measured this site's export by gzipping the actual chunks referenced in index.html, the real number was 105.4 kB vs the table's 107. Close — but trust the export, not the table, and measure the export in CI.

Forensic tool #1: the bundle analyzer, read correctly

npm i -D @next/bundle-analyzer
ANALYZE=true next build

The treemap is where intuitions die. Reading rules:

• Sort by gzipped size. Raw size overweights repetitive code that compresses well.
• Look for duplicates first: two versions of the same library (a date library imported directly and via a dependency) is the most common silent 20 kB.
• Anything in the shared chunk gets interrogated: why is this on every page?

Forensic tool #2: the barrel-file trap

A "barrel" is an index.ts that re-exports a whole library. Icon libraries are the classic case:

import { ArrowUpRight } from "lucide-react"; // innocent-looking

Whether this ships one icon or the entire icon set depends on the library's internal structure and your bundler's tree-shaking succeeding — and tree-shaking fails quietly: a single side-effectful module in the chain and you ship 1,400 icons to render three.

Defenses, in order of preference:

1. Next.js ships optimizePackageImports in next.config — it rewrites barrel imports to direct per-module imports at build time for listed packages (several popular ones are covered by default).
2. Import from the concrete path (lucide-react/dist/esm/icons/arrow-up-right) where the library supports it.
3. For a handful of icons: don't import an icon library at all. This site's icons are ~10 inline SVGs pasted into components. Zero dependency, zero risk, styleable with currentColor.

Forensic tool #3: "use client" contagion

The App Router's real performance feature is that server components ship zero component JavaScript. But client-ness is contagious downward: mark one high-level component "use client" and every module it imports joins the client bundle.

The audit is grep-shaped:

grep -rn '"use client"' src/ | wc -l

Then, for each hit, one question: does this component hold state or attach event handlers? If not, the directive is contagion damage.

This was the single biggest lever on this site. The old version had client components everywhere because everything animated. After the redesign, the page-specific chunk for the home route is 1.88 kB — the interactive surface is exactly four small components (theme toggle, scroll-spy, copy-email button, a 2 kB vitals reporter), and everything else renders on the server at build time. The old page chunk was 55 kB. Nothing was "optimized"; the client boundary was just drawn where it belonged.

Forensic tool #4: know what a dependency costs before you add it

The 68 kB this site lost came mostly from deleting three things the old version shipped: an animation library (~40 kB gz) that animated one decorative beam, a particle engine for section-title sparkles, and a canvas glitch effect. Each entered the codebase as a one-line npm install that looked free.

The discipline that prevents the relapse:

• Check bundlephobia or npm pack --dry-run before installing.
• Prefer the platform: CSS scroll-driven animations replaced the animation library here at a cost of 0 kB — they run compositor-side, which is also better for INP.
• next/dynamic is for genuinely-heavy, genuinely-conditional things (an editor, a chart, a modal). It is not absolution for shipping too much; a lazy-loaded 200 kB is still 200 kB when it loads.

The guardrail that makes it stick

Every number above decays without enforcement. This repo's CI fails any push where the measured export exceeds budget:

// scripts/measure-perf.mjs (excerpt) — gzip the chunks the HTML actually references
const scripts = [...html.matchAll(/<script src="(\/_next\/[^"]+\.js)"([^>]*)>/g)]
  .filter((m) => !m[2].includes("noModule"))
  .map((m) => m[1]);
let jsKb = 0;
for (const src of new Set(scripts)) jsKb += gzKb(await readFile(join(OUT, src)));
if (jsKb > BUDGET.firstLoadJsKb) process.exit(1);

Twenty lines, no SaaS, runs in seconds. The live results are public. A budget that fails the build is a decision; a budget in a wiki is a wish.

The one-hour audit, condensed

1. next build → write down First Load JS per route and the shared row.
2. Analyzer → find duplicates and the heaviest three modules → justify or kill each.
3. Grep "use client" → push every directive down to the smallest stateful leaf.
4. Check barrel imports against optimizePackageImports.
5. Add the CI gate so you never do this audit again.

The pattern behind all five steps is the same one behind most performance work: the bundle doesn't need optimizing so much as it needs auditing. Most of the weight was never load-bearing.

Open DevTools → Network → "Disable cache" → throttle to Fast 4G → reload. Follow along on any site — or this one.

The vocabulary: what one bar means

Every request bar decomposes into segments, and each segment blames a different culprit:

• Queueing / stalled — the browser knew about the resource but chose to wait: lower priority, or (on HTTP/1.1) no free connection. Blames: prioritization, protocol.
• DNS → TCP connect → TLS — the cost of talking to a new origin for the first time, easily 100–300 ms on mobile. Paid once per origin. Blames: third-party sprawl.
• Waiting (TTFB) — request sent, waiting for the first response byte. Blames: the server — or your redirect chain.
• Content download — first byte to last. Long bars here are the only segment that actually blames file size.

First diagnostic reflex: is the time in connection setup, waiting, or download? Engineers who skip this reflex optimize images when the problem is a 600 ms TTFB, or blame the backend when the problem is 4 MB of JavaScript.

The six shapes of a broken waterfall

Individual bars matter less than the shape of the whole chart. Six patterns cover most broken sites:

1. The staircase. Each request starts only after the previous finishes: CSS → font, or JS → JS → fetch. Each step is a full round trip. Classic causes: CSS @import (a stylesheet that downloads another stylesheet), fonts (HTML → CSS → font is an unavoidable two-step you can shorten with preload), and dynamic import() chains. Fix: flatten — inline, preload, or bundle the chain away.

2. The blocking wall. A vertical line early in the chart that nothing renders before: synchronous scripts in <head>, or a pile of render-blocking stylesheets. Everything to the left of first paint is the wall. Fix: defer/async/type=module scripts, split non-critical CSS, and interrogate every third-party tag that demands to load first.

3. The late hero. The LCP image starts downloading at the 2-second mark of a 3-second load. The download was fast; the discovery was slow — it was a CSS background-image (found only after CSS parsed), or behind a lazy-load attribute, or injected by JavaScript. Fix: make the hero an <img> in the initial HTML with fetchpriority="high", and never loading="lazy" above the fold. Discovery time, not transfer time, is the #1 LCP killer I see.

4. The gap. A horizontal stretch where the network is silent — nothing downloading. The network isn't your problem; the main thread is. The browser is parsing a megabyte of JavaScript and hasn't gotten around to requesting the next resource. Fix in the Performance panel, not the Network panel.

5. The third-party cliff. The chart doubles in row-count at some timestamp: one tag manager fired and injected analytics, pixels, session replay, an A/B tool, and a chat widget, each opening a new origin (see: connection setup, above). Fix: audit which of them anyone still uses; façade the chat widget; load the rest after first interaction.

6. The redirect chain. The very first bar is 3 short bars: http://site.com → https://site.com → https://www.site.com. Each hop is a round trip before your HTML even starts, and it taxes every single visit. Fix: one canonical origin, one 301, and links that point at the final URL.

Tracing the critical path

The professional move is reading the waterfall backwards. Find the LCP element (Performance panel → LCP marker, or PageSpeed Insights names it). Then ask, recursively: what did this resource wait for?

LCP image → discovered by CSS (background-image) → CSS waited on a font CDN's preconnect → which waited on the redirect chain.

That chain is the critical path. Nothing off that path matters for LCP, no matter how big it looks in the chart. A 2 MB analytics bundle that loads after the hero paints is a battery problem and an INP risk — but it's not why LCP is slow, and "optimizing" it won't move the metric anyone's dashboard is red about. Precision about which problem you're solving is most of what separates a perf engineer from a checklist.

Priorities are the subplot here: browsers schedule HTML/CSS/fonts as Highest, visible images high, async scripts low — and you can see the assigned priority in the Network panel's Priority column. When the order looks wrong (analytics before hero image), the fix is usually fetchpriority, preload, or moving the offender out of the head — not more bandwidth.

Lab, field, and which waterfall to trust

DevTools shows your machine on your network with your extensions injecting noise. WebPageTest gives you a clean, repeatable waterfall on real mid-range hardware with film-strip screenshots — it remains the gold standard for diagnosis. Field data (CrUX, your own RUM) tells you which pages and which percentiles hurt real users, so you know which waterfall to record in the first place. The workflow that works: field data to pick the target, lab waterfall to find the mechanism, field data again to confirm the fix landed.

Practice on this page

This site is a deliberately boring waterfall — that's the point of it. Reload with the Network tab open and you'll see the whole story: one HTML document, one stylesheet, two latin font subsets, a handful of async chunks, images that wait politely below the fold, and zero third-party origins. Boring is what fast looks like. The full annotated tour is here.

The skill compounds fast: after a dozen deliberate reads, you'll glance at a waterfall and see the diagnosis before you've consciously read a single bar. It's the closest thing performance work has to a superpower — and it's free.

Everything below is applied on this site; the numbers are from its build output, and you can verify them in your Network tab right now.

Compression: woff2 or nothing

Font formats are a solved argument. woff2 wraps the font tables in Brotli compression and has been supported by every browser that matters for years. Compared to a raw ttf/otf, woff2 is typically 60–70% smaller; compared to the older woff (zlib-based), it still saves ~20–30%.

Practical rules:

• Ship woff2 only. A woff fallback in your @font-face src list is dead weight in 2026 — browsers that would use it can live with your fallback stack.
• Never ship ttf/otf to production. If a designer hands you one, convert it (fonttools does this in one line).
• Don't double-compress: woff2 is already Brotli. Serving it with Content-Encoding: br again wastes CPU for ~0 bytes. Check your CDN isn't doing this.

Subsetting: the 80% you never render

A typical "full" font covers Latin, Latin Extended, Cyrillic, Greek, Vietnamese, and a pile of OpenType features. If your site is English-language, most of those bytes are decoration for the crawler.

Subsetting splits the font by script and lets unicode-range do lazy loading at the glyph level:

@font-face {
  font-family: "Geist";
  src: url("/fonts/geist-latin.woff2") format("woff2");
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, /* … */;
}

The browser downloads a subset only if the page actually renders a character in its range. This site declares eleven subset files for its two families, but a typical visit downloads exactly two: the Latin subsets — 28.6 kB for Geist Sans and 22.6 kB for Geist Mono. The other nine files exist for the rare page that needs them and cost nothing until then.

Tooling: next/font does this automatically (it's what generated the numbers above). Doing it by hand, pyftsubset from fonttools is the standard:

pyftsubset Geist.ttf \
  --output-file=geist-latin.woff2 \
  --flavor=woff2 \
  --layout-features="kern,liga,calt" \
  --unicodes="U+0000-00FF,U+2013-2014,U+2018-201D,U+2026"

Two traps worth knowing: aggressive subsetting can silently drop ligatures, tabular figures, or the arrows and quotes your design system actually uses — keep the OpenType features you rely on, and test with real content. And if you support user-generated content, be generous with ranges; tofu boxes (□) in a comment section are a worse bug than 10 extra kilobytes.

Variable fonts: one file instead of six

If you use more than two or three weights of a family, a variable font usually wins. Instead of shipping Regular + Medium + SemiBold + Bold as four files, one variable file carries the whole weight axis — typically 40–60% smaller than the sum, one request instead of four, and you get the in-between weights for free.

The flip: if you only use one weight plus a bold, two static subsets are often smaller than one variable file. Measure, don't assume — the answer flips per family.

Loading strategy: FOUT is a feature

font-display decides what happens between first paint and font arrival:

• swap — show the fallback immediately, swap when ready. Text is readable from the first paint. This is the right default for body text.
• optional — use the web font only if it's already cached (or arrives near-instantly). The most performance-pure option: repeat visitors get the brand font, first-time visitors on slow networks never wait for it.
• block — invisible text for up to 3 seconds. Almost never what you want.

People avoid swap because the swap itself looks janky: the fallback renders at a different width, and the page reflows when the real font lands. That's not an argument against swap — it's an argument for fixing the fallback. Which brings us to the good part.

size-adjust: the layout shift killer

The reflow-on-swap problem exists because Arial and your brand font disagree about how wide text is. Modern CSS lets you calibrate the fallback to match the web font's metrics:

@font-face {
  font-family: "Geist Fallback";
  src: local("Arial");
  size-adjust: 104.76%;
  ascent-override: 85.83%;
  descent-override: 20.32%;
  line-gap-override: 9.33%;
}

That 104.76% is a real number from this site's generated CSS: Arial scaled up ~5% occupies almost exactly the same space as Geist, so when the swap happens, nothing moves. The mono fallback needs size-adjust: 134.59% — monospace metrics diverge harder, which is why unstyled mono fallbacks jump so visibly on other sites.

next/font computes these overrides automatically. Outside Next, fontaine or Capsize generate them, or you can measure once with a canvas and hardcode the result. However you get there, this single technique takes font-driven CLS to zero without giving up custom type.

Discovery: when does the browser even ask?

Compression solves bytes; discovery solves when. The browser requests a font only after it has downloaded CSS, built the render tree, and found a visible element using that face. That chain — HTML → CSS → font — is why fonts are chronically late.

• Self-host. A third-party font CDN adds a DNS + TLS handshake to a render-critical resource, and cross-origin caching has been dead since browsers partitioned caches years ago. There is no performance argument left for a font CDN — only licensing ones.
• Preload only what's certain. <link rel="preload" as="font"> skips the discovery chain, but every preloaded font competes with your CSS and LCP image for early bandwidth. Preload the one or two subsets that render above-the-fold text; preloading all eleven subsets would make this site slower.
• Same-origin, immutable caching. Hashed font filenames + Cache-Control: immutable means repeat visits pay zero font cost.

The checklist

1. woff2 only, self-hosted, hashed filenames, immutable cache headers.
2. Subset by script; let unicode-range lazy-load the exotic ranges.
3. Variable font if you use 3+ weights; measure if fewer.
4. font-display: swap (or optional if you're hardcore) — never block.
5. Metric-compatible fallback with size-adjust/ascent-override → zero CLS.
6. Two families maximum. Every additional face has to justify itself against the best-compressed asset on your page: no font at all.

The result on this site: two families, ~51 kB of fonts on a typical visit, zero layout shift, zero third-party requests. Open DevTools → Network → filter "Font" and check my math.