Reading the Browser Waterfall
HTML discovers CSS, CSS blocks the paint, script blocks the parser, and the image nobody prioritised is fetched last. The waterfall shows a dependency chain — and the difference between a resource being downloaded and the page being usable.
Frame the diagnosis
Performance work starts from a symptom and a signal — never from a resource dashboard.
A dependency chain, drawn sideways
A waterfall is not a list of downloads. It is a picture of *discovery*: the browser cannot fetch what it has not parsed, so a resource referenced by a stylesheet or injected by a script is discovered late no matter how small it is. The long bars are often symptoms; the position of a bar is usually the cause.
In the waterfall below, the hero image is 620ms of download — but the actionable fact is that it *starts* at 1600ms, because it is injected by the script that finishes executing at 1560ms. Making the image smaller shaves a little off the end. Making it discoverable in the initial HTML moves its start by more than a second.
This is the same critical-path reasoning as in The Critical Path Is the Only Path That Pays, applied to a browser rather than a service graph: find the chain of dependencies where each link cannot begin until the previous ends, and shorten a link that is actually on it.
Render-blocking is a chain, not a list
Two mechanisms hold up the first paint, and they behave differently. A stylesheet blocks *rendering*: the browser will happily keep parsing HTML and discovering resources, but it will not paint until the CSS has arrived and been parsed. A classic synchronous script blocks *parsing*: the parser stops dead, so nothing after that tag is even discovered until the script has downloaded and run.
The parser-blocking case is the more damaging one and the easier to miss, because the cost does not appear as a long bar on the script — it appears as an unexplained gap before everything that follows. A 200ms script in the head can delay the discovery of a hero image by 200ms plus the entire cost of executing it.
The preload scanner mitigates some of this by speculatively looking ahead for fetchable URLs while the parser is blocked, which is why <img src> in the initial HTML behaves so much better than an image URL that only exists after JavaScript runs. Anything the scanner cannot see — script-injected resources, CSS url() references, dynamic imports — is discovered late by construction.
Downloaded is not usable
The waterfall ends when the last byte arrives, and users do not care about bytes. Between "downloaded" and "usable" sit parse, compile, execute, layout and paint — main-thread work that a network-shaped view of the world renders invisible.
This is why a team can move a site to a CDN, watch every bar in the waterfall shrink, and receive exactly the same complaints. The bytes arrive faster; the 600ms of script execution that follows them is unchanged, because it is CPU on a device you do not control.
Read the waterfall together with a main-thread timeline. If the bars are short and the gap after them is long, the constraint is the device, and the fix belongs in JavaScript Costs Four Times, Not Once or Layout, Paint and the Main Thread rather than in the network.
| Signal | Value | What it tells you | Verdict |
|---|---|---|---|
| Total transferred bytes | unchanged | A CDN moves bytes closer; it does not remove them | normal |
| Asset download time | 520ms → 180ms | Genuine improvement in the network portion | normal |
| JS parse + compile + execute | 610ms → 610ms | Device CPU is untouched by where the bytes came from | smoking gun |
| LCP, field p75 mobile | 4.2s → 3.9s | Moved by roughly the network saving and no more | suspect |
| INP, field p75 mobile | 380ms → 385ms | Unchanged — the main thread is just as busy as before | smoking gun |
Key points
- A waterfall shows discovery order and dependency, not just size — a bar's start time is usually more actionable than its length.
- Stylesheets block rendering; synchronous scripts block parsing, which also blocks the discovery of everything after them.
- The preload scanner can only speculatively fetch what is visible in the HTML; script-injected and CSS-referenced resources are late by construction.
- The waterfall ends at the last byte; the user waits for parse, compile, execute, layout and paint that a network view does not show.
- Shortening a resource that is not on the critical chain changes the picture and not the experience.
Browser Waterfall
Change an input and watch which number moves — and which one does not.
The API call is 190 ms of 3,200. The largest file — a 1.4 MB image — blocks nothing. The actual critical path runs HTML → CSS → JavaScript download → JavaScript execution, and the single biggest item on it is parse + compile + execute, which no amount of compression improves.
Follow the diagnosis
The causal chain, hop by hop — and the readings that invite the wrong conclusion.
- 1Parser → CSS: the stylesheet is discovered immediately and fetched; the browser will not paint anything until it parses.
- 2Parser → script: the bundle is fetched in parallel by the preload scanner, but must execute on the main thread before it can do anything.
- 3Script → DOM: the hero image element is created at 1560ms, which is the first moment the browser learns that hero.jpg exists.
- 4Browser → CDN: hero.jpg is fetched starting at 1600ms — a fast fetch that started far too late.
- 5Layout → user: the LCP element paints at 2280ms, having spent more time waiting to be discovered than waiting to be downloaded.
- • "The hero image is the biggest bar, so compress it." Its start time is the problem; compressing it saves a fraction of what moving its discovery saves.
- • "All the resources download quickly, so the network is fine." Fast downloads that start late still produce a slow page.
- • "Moving to a CDN will fix it." A CDN shortens the bars and leaves the main-thread work — and often the discovery order — exactly as it was.
- • "The script is only 40ms of execution in my profiler." Check the device: execution cost on a mid-range phone can be several times a laptop's.
- • "Nothing is blocking — there are no long bars." Look for gaps, not bars. A parser-blocking script shows up as absence, not length.
Measure, fix, validate
An optimization is not finished until the metric that motivated it has moved.
- • The full resource waterfall for a cold first visit on a throttled mid-range device profile, with start times and priorities visible.
- • Which element is the LCP element, and the timestamp at which its fetch was *initiated* rather than completed.
- • Resource Timing entries for the LCP resource: `startTime`, `responseEnd`, and the initiator that discovered it.
- • A main-thread timeline for the same load, to separate network bars from the execution that follows them.
- • Whether each blocking resource is parser-blocking or render-blocking — they need different fixes.
- • Make the LCP resource discoverable in the initial HTML markup so the preload scanner finds it immediately, and give it explicit fetch priority.
- • Remove parser-blocking scripts from the head, or mark them so they do not stop the parser discovering later resources.
- • Inline the small amount of CSS needed for the first screen and load the rest without blocking the paint.
- • Cut or defer script that the first screen does not need, which attacks both the download bar and the execution gap after it (see [[javascript-bundle-cost]]).
- • Only then optimise the bytes themselves — format, compression and dimensions (see [[image-performance]]).
- • Re-run the same throttled cold-load profile and confirm the LCP resource's *start* time moved, not only its duration.
- • Confirm field LCP p75 for the affected route and device segment moved over a stable window, not just the lab number.
- • Check the main-thread timeline: if the bars shrank and the gap did not, the remaining cost is execution and needs a different fix.
- • Verify no resource was starved by the new priority — over-prioritising the hero can simply push the delay onto something else.
- • Inlining critical CSS duplicates bytes across pages and complicates caching — a real cost paid for an earlier first paint.
- • Preloading and priority hints compete for the same bandwidth; prioritising everything prioritises nothing.
- • Server-rendering the hero markup to make it discoverable can increase TTFB, trading backend time for earlier discovery.
- • Deferring script improves the paint and can worsen interaction readiness if the deferred work then lands during a user's first tap.
- • A CI check that the LCP element for each key route is present in the server-rendered HTML rather than script-injected.
- • A budget on render-blocking bytes in the head, enforced per commit.
- • A synthetic waterfall snapshot per commit for the top routes, diffed for newly-blocking resources.
- • A review rule that any newly added third-party script states where it loads and whether it blocks the parser.
Accuracy
Performance numbers are conditional. These are the conditions.
- WEB-SPECIFICDiscovery, preload scanning and render-blocking semantics are browser behaviours; the details vary between engines and change between versions.
- ILLUSTRATIVEThe waterfall timings are invented to show the shape of a script-injected LCP. Real timings depend on device, connection, HTTP version and cache state.
- ENVIRONMENT-SPECIFICThe number of resources fetched in parallel and their priority handling depend on the HTTP version and connection reuse — HTTP/1.1 and HTTP/2 produce visibly different waterfalls.