completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

Project: a performance pipeline

Add budgets, a size check for every file and Lighthouse CI to a store's repository, and report on pull requests, so slow changes fail before they merge.

By the end, you can
  • 01
    Choose budgets from your own numbersMeasure main the way the check will, leave room above the wobble, and write each budget down with its reason.
  • 02
    Check bytes and pages on every pull requestCheck every file's gzip size, and run Lighthouse CI five times on each page, judged by the middle run.
  • 03
    Put the answer on the pull requestWrite a workflow that fails the check, fills the job summary and keeps one comment up to date, with only the permissions it needs.

Two pull requests, and a pipeline that checks both

Leaf and Kettle is fast now. In lesson 45.1, Ravi fixed the Mint tea page. In lesson 45.2, he built a dashboard of the store's real visits. In lesson 45.3, he made the Tea finder's taps quick.

It's Friday, and two pull requests are waiting. A pull request asks to merge a branch into main, the code the site runs. A branch is a copy of the code where one person makes a change.

  • Ben's pull request makes the cart say how many teas it holds: "Cart: 2 teas".
  • Meera, the designer, brings back the paper texture on the mint tea picture. On screen, it looks almost the same.

Ravi has one question. Would either change make the store slow again? Until now, someone had to remember to measure. Or the field data would say so a week later, after visitors had felt it. This project makes the store's repository answer on every pull request, in a few minutes. A repository is the folder of code that git keeps, with its whole history.

Here is where the project ends. These are the checks' answers on the two pull requests:

What the checks found on each pull requestPop out in the code editor (opens in a new tab)JavaScript
// What the checks found on each pull request: the file it changed, and the Mint tea page's LCPconst prs = [  { branch: "ben/cart-words", file: "app.js", gzip: 12936, budget: 14200, lcp: 1202 },  { branch: "meera/textured-picture", file: "hero.svg", gzip: 77756, budget: 1100, lcp: 1511 },];const lcpBudget = 1300;for (const pr of prs) {  const bytes = pr.gzip <= pr.budget ? "within budget" : "over budget";  const lcp = pr.lcp <= lcpBudget ? "within budget" : "over budget";  console.log(`${pr.branch}: ${pr.file} ${bytes}, LCP ${lcp}`);}
  • Line 1 is a comment.
  • Lines 3 and 4 hold recorded numbers. gzip is the file's size in bytes once it's packed for sending, and budget is its limit. lcp is the Mint tea page's LCP, Largest Contentful Paint: when the biggest thing on the screen appeared. It's the middle of five lab runs, in milliseconds (ms).
  • Line 6 is the LCP's limit. Lines 8 and 9 compare each number with its limit.
  • It prints ben/cart-words: app.js within budget, LCP within budget and meera/textured-picture: hero.svg over budget, LCP over budget.

Ben's change passed. Meera's failed twice. Her picture was 77,756 bytes instead of 993. And the page's LCP came 309 ms later than on Ben's. Why it matters: Meera learns this on her pull request, before any visitor does.

Here is the whole pipeline, from a push to the answer on the pull request:

A push to a pull request starts one job on GitHub Actions. Its steps, in order: node scripts/check-size.mjs, lhci collect: 5 runs a page, lhci assert: the medians, lhci upload: save reports, node scripts/report.mjs. The job gives three answers: the check (pass or fail), job summary (the report, on the run), PR comment (the report, on the PR).One job on every pull requestgit pushto a branchbudgets job1 node scripts/check-size.mjs2 lhci collect: 5 runs a page3 lhci assert: the medians4 lhci upload: save reports5 node scripts/report.mjsthe checkpass or failjob summarythe report, on the runPR commentthe report, on the PR
Every push to a pull request runs the same five steps on a fresh machine. The shaded steps compare numbers with budgets.json and can fail the job. The answer comes back three ways: the check, the job summary and one comment.
Real-life analogyChecks at the bakery door

A bakery sends trays of bread to its shop every morning. At the door, each tray gets the same checks. Every loaf is weighed, and one is tasted. A tray that fails gets a slip saying which check failed, and why. The baker finds out before the shop opens, not from a customer.

In real life: A tray of bread
In web performance: A pull request
In real life: Weighing every loaf
In web performance: The size check: every file's bytes
In real life: Tasting one loaf from the tray
In web performance: Lighthouse CI: each page in a lab browser
In real life: The slip on a tray that fails
In web performance: The report on the pull request
In real life: Before the shop opens
In web performance: Before the change is merged
The main idea

A performance pipeline writes each budget down once, with its reason. It checks every pull request against them: bytes exactly, and lab timings by the middle of several runs. Then it puts the answer on the pull request, where the author looks. A budget is a limit the team agrees not to cross. The pipeline makes crossing it fail the build.

The project has four steps:

  • Step 1: choose budgets from the store's own numbers, with a reason for each.
  • Step 2: check the size of every file the store sends.
  • Step 3: run Lighthouse CI on both pages, five times each.
  • Step 4: report the answer on the pull request.

Build each step on your own copy of the store. Put the store's files from lessons 45.1 to 45.3 in a folder called site/, with each page.html saved as index.html. Make the folder above it a git repository. The course's files for each step are published:

How the course recorded it

  • The repository: a git repository on the course's computer. First the store, then the pipeline's files, then one branch for each pull request. Each branch is one commit on top of main.
  • The jobs: the workflow's own commands, in its order, on each branch. First three jobs on main with no limits, for the budgets. Then three rounds of main, Ben's and Meera's branches, taking turns. Then one job each for six more changes. That's 15 jobs with budgets, and 180 Lighthouse runs in all, counting the first three jobs.
  • The tools: Lighthouse CI 0.16.1, with Lighthouse 13.6.0, in Chrome for Testing 157.0.8103.52. Node.js 22.23.3 for the two scripts. actionlint 1.7.12, with ShellCheck 0.11.0, for the workflow file.

Step 1: choose budgets from the store's own numbers

Choosing the numbers is the hard part. Too tight, and a budget fails changes that are fine. Too loose, and it never fails at all. Lesson 39.1 set the rule: start from where you are today, not from where you'd like to be.

Ravi already has numbers. On real phones, the Mint tea page's LCP is 520 ms at the p75: three visits in four were that fast or faster. The finder's INP p75 is 56 ms. Those are what visitors feel.

But a check on a pull request can't wait for visitors. It runs in a lab, with Lighthouse, before the change goes live. And numbers from one tool only compare with the same tool's (lesson 39.2). So Ravi first measures main the way the check will: three Lighthouse CI jobs, five runs on each page.

main's numbers, and two budgets from themPop out in the code editor (opens in a new tab)JavaScript
// main's LCP on the Mint tea page: 15 Lighthouse runs, in msconst lcps = [1219.9, 1216.3, 1217.7, 1242.3, 1255.6, 1204, 1207.1, 1200.6, 1206.6, 1207.3, 1202.9, 1201.9, 1198.8, 1201.9, 1202.7];const timeBudget = (slowest) => Math.ceil(slowest / 100) * 100;const fileBudget = (gzip) => Math.ceil((gzip * 11) / 1000) * 100; console.log(`LCP: ${Math.min(...lcps)} to ${Math.max(...lcps)} ms, budget ${timeBudget(Math.max(...lcps))}`);console.log(`hero.svg: 993 bytes, budget ${fileBudget(993)}`);
  • Line 2 holds the 15 LCPs Lighthouse measured on the Mint tea page, in ms.
  • Line 3 is lesson 39.1's rule for timings: the slowest run, rounded up to the next 100 ms. Math.ceil() rounds up.
  • Line 4 is its rule for bytes: today's size plus a tenth, rounded up to the next 100 bytes.
  • Lines 6 and 7 print LCP: 1198.8 to 1255.6 ms, budget 1300 and hero.svg: 993 bytes, budget 1100.

The same page, measured 15 times, gave 14 different LCPs, up to 56.8 ms apart. The budget sits above all of them. Why it matters: a limit inside that spread would fail some runs of main itself.

Real-life analogyA fridge's warning light

A fridge sits between 3 and 5 °C. Each time someone opens the door, it warms a little, then cools again. Its warning light comes on at 8 °C. That's above the door's normal wobble, so it never flashes for a snack. But if the door stays open all night, it comes on.

In real life: The fridge's normal 3 to 5 °C
In web performance: main's runs, a little different each time
In real life: The door opening for a moment
In web performance: The wobble from run to run
In real life: The warning light at 8 °C
In web performance: The budget, with room above the wobble
In real life: The door left open all night
In web performance: A real slowdown, like Meera's picture

Ravi writes the rules into the file, so the next person knows them:

  • Files: main's gzip size plus a tenth, rounded up to the next 100 bytes.
  • Timings: main's slowest of 15 Lighthouse runs, rounded up to the next 100 ms. TBT: at least 100 ms.
  • Page bytes: main's plus a tenth, rounded up to the next 1,000.
  • Layout shifts: Google's good line, 0.1. Requests to other sites: none.

Every budget goes in one file, budgets.json, and each one says why. Both checks read it. Here are two of its 22 budgets:

budgets.json: two of its budgetsJSON
{  "files": {    "hero.svg": {      "gzip": 1100,      "why": "Main sends 993 bytes. The LCP picture. With the textured one, LCP was 6.5 s in lesson 45.1."    }  },  "pages": {    "/": {      "largest-contentful-paint": {        "max": 1300,        "why": "Main's slowest of 15 runs: 1,256 ms, rounded up. Lesson 45.1 cut this page's LCP from 6.5 s to 1.3 s."      }    }  }}
  • Lines 3 to 6 are the picture's budget. Line 4 is the limit in gzip bytes. Line 5 is the reason, with main's number in it.
  • Lines 10 to 13 are the Mint tea page's LCP budget. Line 11 is the limit, in ms. Line 12 says where it came from, and what it protects.

Each reason holds the number it came from. When a budget fails, the report shows that reason, so nobody has to guess what the limit was for. Read each row of the table across: the budget, main's number, and the limit.

Some of the store's budgets
BudgetWhat did main have?The limitWhy this limit?
Mint tea page, LCP1,199 to 1,256 ms1,300 msMain's slowest of 15 runs: 1,256 ms, rounded up. Lesson 45.1 cut this page's LCP from 6.5 s to 1.3 s.
Mint tea page, TBT94 to 103 ms200 msMain's slowest of 15 runs: 103 ms, rounded up. Lighthouse doesn't tap, so this stands in for INP.
Mint tea page, all bytes23,274 bytes26,000 bytesMain's page sends 23,274 bytes in all, plus a tenth.
Tea finder, LCP753 to 1,668 ms1,700 msMain's slowest of 15 runs: 1,668 ms, rounded up. Google's good line is 2,500 ms.
hero.svg, gzip993 bytes1,100 bytesMain sends 993 bytes. The LCP picture. With the textured one, LCP was 6.5 s in lesson 45.1.
app.js, gzip12,904 bytes14,200 bytesMain sends 12,904 bytes. The 1,800-tea catalogue and the Add button (lesson 45.1).

Some budgets can't start from main's slowest run, because that run is 0. A layout shift uses Google's good line, 0.1. The finder's Total Blocking Time, or TBT, gets a floor of 100 ms. TBT adds up how long the page was too busy to answer a tap. And requests to other sites stay at zero: lesson 45.1 put the chat widget behind a tap, and this keeps it there.

How much room is right? Slide it, and watch every job the course ran. Each budget starts at main's usual number before any budget existed: the middle run for timings, and the bytes for sizes. Then it adds the room:

Playground: how much room above main?
The budgets at this room
  • Mint tea page LCP1,327 ms (main: 1,207 ms)
  • Mint tea page TBT106 ms (main: 96 ms)
  • Mint tea page bytes25,601 bytes (main: 23,274 bytes)
  • Tea finder LCP1,821 ms (main: 1,656 ms)
  • app.js, gzip14,194 bytes (main: 12,904 bytes)
  • hero.svg, gzip1,092 bytes (main: 993 bytes)
  • Mint tea page CLS0.1, fixed
  • Requests to other sites0, fixed
  • Files with no budget0, fixed
Changes that are fine
  • main, round 1passes
  • Ben's cart words, round 1passes
  • main, round 2passes
  • Ben's cart words, round 2passes
  • main, round 3passes
  • Ben's cart words, round 3passes
Changes that make it worse
  • Meera's textured picture, round 1fails: Mint tea page LCP, Mint tea page TBT, Mint tea page bytes, hero.svg, gzip
  • Meera's textured picture, round 2fails: Mint tea page LCP, Mint tea page bytes, hero.svg, gzip
  • Meera's textured picture, round 3fails: Mint tea page LCP, Mint tea page TBT, Mint tea page bytes, hero.svg, gzip
  • app.js without deferpasses
  • no room for the promotionfails: Mint tea page CLS
  • all of Swiperfails: Mint tea page LCP, Mint tea page bytes, Files with no budget
  • the chat widget on every loadfails: Requests to other sites
  • Add to cart redraws every teafails: Mint tea page TBT
  • a lighter texture, 300 dotsfails: hero.svg, gzip
Try it yourself
10% room: 0 of 6 good jobs fail, 8 of 9 problem jobs fail

Each budget starts at main's usual number before any budget existed, plus the room: the middle run for timings, the bytes for sizes. Three budgets don't move with the room: CLS stays at Google's good line, and requests to other sites and files with no budget stay at zero.

Every job the course ran: main, Ben's change and Meera's picture three times each, and 6 replayed problems once. Lighthouse numbers are each job's middle run, in Chrome 157.0.8103.52.

With no room, most of the good jobs fail: main's own wobble, and Ben's few extra bytes. With a lot, the LCP budget lets Meera's picture through, though the picture's own size budget still catches it. Budgets back each other up. Ravi's LCP budget for the Mint tea page, 1,300 ms, is 8% above main's middle run.

Look at the slow Add button at small rooms: it fails on TBT, by a few ms. Its page loads the same code as main's, and its slow work runs only on a tap. That's the wobble, not a catch. Why it matters: the right room is the smallest one that keeps good changes green. Bytes need room only for small changes. Timings need room for the wobble too.

Step 2: check the size of every file

Bytes are the easy check: the same files always have the same size. Lesson 39.1 checked two named files with size-limit. Ravi wants every file the store sends, the picture and the finder's catalogue too. A short script does it, in three parts.

check-size.mjs, part 1: the budgets and the filesJavaScript
// check-size.mjs: every file in site/ against its gzip budget in budgets.json.import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";import { brotliCompressSync, gzipSync } from "node:zlib"; const budgets = JSON.parse(readFileSync("budgets.json", "utf8")).files;const files = readdirSync("site", { recursive: true })  .filter((name) => statSync(`site/${name}`).isFile())  .sort();
  • Lines 2 and 3 bring in Node.js's file and compression functions.
  • Line 5 reads budgets.json and keeps its files part.
  • Lines 6 to 8 list every file in site/, in folders too, like finder/app.js. They keep files, not folders, in order.
check-size.mjs, part 2: two sizes and a verdict for each fileJavaScript
const rows = files.map((file) => {  const bytes = readFileSync(`site/${file}`);  const gzip = gzipSync(bytes).length;  const brotli = brotliCompressSync(bytes).length;  const budget = budgets[file]?.gzip ?? null;  return { file, gzip, brotli, budget, passed: budget !== null && gzip <= budget };});
  • Line 2 reads one file's bytes.
  • Line 3 packs them with gzip, at zlib's default level, 6. Line 4 packs them with Brotli, at its top level, 11. Lesson 16.1 compared the two.
  • Line 5 looks up the file's budget. ?. and ?? null give null when the file has none.
  • Line 6 passes a file only if it has a budget and its gzip size fits.
Real-life analogyChecking a delivery against the order sheet

A shop gets a delivery with an order sheet. The sheet lists every box and what it should weigh. The shopkeeper weighs each box as it comes in. A box that's too heavy goes back. So does a box that isn't on the sheet at all, because nobody ordered it.

In real life: The order sheet, with a weight for each box
In web performance: budgets.json's files part
In real life: Weighing every box that arrives
In web performance: gzipping every file in site/
In real life: A box heavier than the sheet says
In web performance: A file over its budget
In real life: A box that isn't on the sheet
In web performance: A file with no budget: it fails too
check-size.mjs, part 3: print, save and pass or failJavaScript
const n = (bytes) => bytes.toLocaleString("en-US").padStart(8);console.log(`${"File".padEnd(26)}    gzip  Brotli  Budget`);for (const row of rows) {  const verdict = row.passed ? "ok" : row.budget === null ? "NO BUDGET" : `OVER by ${(row.gzip - row.budget).toLocaleString("en-US")}`;  console.log(`${row.file.padEnd(26)}${n(row.gzip)}${n(row.brotli)}${row.budget === null ? "    none" : n(row.budget)}  ${verdict}`);} const failed = rows.filter((row) => !row.passed);console.log(`${rows.length} files: ${failed.length === 0 ? "all within budget." : `${failed.length} failed.`}`);writeFileSync("size-report.json", `${JSON.stringify(rows, null, 2)}\n`);process.exitCode = failed.length === 0 ? 0 : 1;
  • Lines 1 to 6 print one row per file: its gzip size, its Brotli size, its budget, and a verdict.
  • Line 8 keeps the files that failed. Line 9 prints how many.
  • Line 10 saves every row to size-report.json, for the report in step 4.
  • Line 11 sets the exit code, the number a program ends with. 0 means it passed, and 1 means it failed. A failed step fails the job.

Here is what it printed on Meera's pull request:

The size check on Meera's pull requestText
$ node scripts/check-size.mjsFile                          gzip  Brotli  Budgetabout.html                     342     230     400  okapp.js                      12,904   6,191  14,200  okfinder/app.js                1,841   1,540   2,100  okfinder/index.html              440     283     500  okfinder/search-worker.js        818     683     900  okfinder/styles.css              558     405     700  okfinder/teas.json            65,322  40,202  71,900  okhero.svg                    77,756  66,481   1,100  OVER by 76,656index.html                     611     439     700  okrum.js                         562     429     700  okstyles.css                     359     276     400  okweb-vitals.attribution.js    5,542   5,026   6,100  ok12 files: 1 failed.

Line 10 is Meera's picture: 77,756 bytes, over its budget by 76,656. The textured picture has 14,000 dots drawn in it, and each one is text in the file. Every other file passed. On Ben's pull request, app.js grew by 32 bytes, to 12,936, and all 12 files passed.

Why gzip? The store's host sends files gzipped, the way lesson 45.3 recorded them. The budget counts what visitors download (lesson 22.1). The Brotli column shows what switching would save. The catalogue, finder/teas.json, would go from 65,322 to 40,202 bytes.

A new file with no budget fails too. Here is a branch that adds all of Swiper, the carousel library from lesson 39.1:

The size check on a branch that adds SwiperText
$ node scripts/check-size.mjsFile                          gzip  Brotli  Budget...vendor/swiper-bundle.min.js  44,493  38,629    none  NO BUDGET13 files: 1 failed.

Line 4 is the new file: 44,493 bytes with gzip, and NO BUDGET. Why it matters: nothing can slip in unchecked. Adding a file means adding its budget, with a reason, in the same pull request, where a reviewer reads it.

Step 3: run Lighthouse CI on both pages

Bytes don't say when the picture appears. For that, the pipeline needs a browser. Lighthouse CI runs Lighthouse on your pages, several times, then checks the results against your limits. Lesson 39.2 showed its three commands: collect, assert and upload. Here, its settings read the same budgets.json:

lighthouserc.cjs: Lighthouse CI's settingsJavaScript
// lighthouserc.cjs: Lighthouse CI's settings. The pages and their limits come from budgets.json.const { pages } = require("./budgets.json"); const assertMatrix = Object.entries(pages).map(([path, limits]) => ({  matchingUrlPattern: `:\\d+${path}$`,  aggregationMethod: "median",  assertions: Object.fromEntries(Object.entries(limits).map(([id, limit]) => [id, ["error", { maxNumericValue: limit.max }]])),})); module.exports = {  ci: {    collect: {      staticDistDir: "./site",      url: Object.keys(pages).map((path) => `http://localhost${path}`),      numberOfRuns: 5,    },    assert: { assertMatrix, includePassedAssertions: true },    upload: { target: "filesystem", outputDir: "./lhci-reports" },  },};
  • Line 2 reads the pages part of budgets.json. A .cjs file can load JSON with require().
  • Lines 4 to 8 make one entry for each page: an assertMatrix. Line 5 picks the page by its address. The pattern :\d+/finder/$ matches the server's port number, then /finder/ at the very end. Line 6 judges each budget by the page's middle run.
  • Line 7 turns each budget into an assertion, a rule Lighthouse CI checks. "error" means a failure fails the step. maxNumericValue is the highest number that passes.
  • Lines 13 and 14 serve site/ from Lighthouse CI's own small server, and visit both pages. Line 15 runs Lighthouse five times on each.
  • Line 17 prints and saves the assertions that passed too, so the report can show every budget. Line 18 saves every report on disk, in lhci-reports/.

The workflow runs the three commands one after another. Here is the first:

lhci collect on Ben's pull requestText
$ lhci collectStarted a web server on port PORT...Running Lighthouse 5 time(s) on http://localhost:PORT/Run #1...done.Run #2...done.Run #3...done.Run #4...done.Run #5...done.Running Lighthouse 5 time(s) on http://localhost:PORT/finder/Run #1...done.Run #2...done.Run #3...done.Run #4...done.Run #5...done.Done running Lighthouse!

Line 2 starts the server. Lines 3 and 9 start five runs on each page, one after another. Lighthouse's own docs say never to run two at once on one machine: they would compete for it and skew each other's numbers.

Why five runs, and the middle one

One run isn't enough, because runs wobble. Lesson 9.4 showed where the wobble comes from. Here are main's runs on the finder, before any budget:

The finder's LCP: each job's best run and middle runPop out in the code editor (opens in a new tab)JavaScript
// main's LCP on the Tea finder: three jobs of five runs, in msconst jobs = [  [1667.5, 1655.7, 1656.2, 1654.7, 753.6],  [1658.2, 1657.2, 753.3, 1657.9, 1654.3],  [1655, 1655.5, 1656.1, 1656, 1655.2],];const middle = (lcps) => [...lcps].sort((a, b) => a - b)[2];for (const lcps of jobs) {  console.log(`best ${Math.min(...lcps)}, middle ${middle(lcps)}`);}
  • Lines 3 to 5 hold three jobs of five LCPs each, in ms.
  • Line 7 sorts a copy of one job's runs and takes the third: the middle one. Line 9 prints the best run and the middle run.
  • It prints best 753.6, middle 1655.7, best 753.3, middle 1657.2 and best 1655, middle 1655.5.

Two of the 15 runs landed near 754 ms. All the others were near 1,656 ms. Same code, same machine. In those runs, the finder's list was already in Chrome's very first frame. So Lighthouse's estimate put the LCP at the first paint (lesson 8.3 showed how it estimates a phone's times).

Every LCP of main's three jobs before any budget, five runs a job, with each job's middle run. Mint tea page, budget 1,300 ms: job 1: 1219.9, 1216.3, 1217.7, 1242.3, 1255.6, middle 1219.9; job 2: 1204.0, 1207.1, 1200.6, 1206.6, 1207.3, middle 1206.6; job 3: 1202.9, 1201.9, 1198.8, 1201.9, 1202.7, middle 1201.9. Tea finder, budget 1,700 ms: job 1: 1667.5, 1655.7, 1656.2, 1654.7, 753.6, middle 1655.7; job 2: 1658.2, 1657.2, 753.3, 1657.9, 1654.3, middle 1657.2; job 3: 1655.0, 1655.5, 1656.1, 1656.0, 1655.2, middle 1655.5.Mint tea page, LCPbudget 1,300job 1job 2job 31,1501,2001,2501,3001,350Tea finder, LCPbudget 1,700job 1job 2job 37501,0001,2501,5001,750
Each thin bar is one run, and the tall shaded bar is its job's middle run. On the finder, two runs landed far from the others. Neither one moved its job's middle run.
Real-life analogyTiming the bus to work

Asha times her bus to work for a week: 24, 23, 25, 24, and 15 minutes on the day every light was green. Asked how long it takes, she says "about 24". The 15 was luck. If she judged a new route by its single best day, every route would look fast.

In real life: Five trips to work
In web performance: Five Lighthouse runs
In real life: The day every light was green
In web performance: A run far faster than the others
In real life: "About 24 minutes"
In web performance: The middle run
In real life: A new bus route
In web performance: A pull request

Lighthouse CI's default, optimistic, judges each page by its best run. That would have judged two of these jobs by a lucky 754 ms. The middle run ignored them. That's why line 6 of lighthouserc.cjs asks for the median.

The middle run has a limit too. In one of Ben's jobs, three of the five finder runs were the fast kind, and the middle run was 757 ms. Ben's change didn't touch the finder. In every job, the finder's middle run was under its budget of 1,700 ms, so the check never failed by chance. But a lucky job could hide a slower finder. Why it matters: five runs smooth out an odd run, not a page that loads two ways. For the finder's real LCP, Ravi trusts the field dashboard from lesson 45.2.

A failure, line by line

Then lhci assert checks each page's middle run against its budgets. Here is how its output began on Meera's pull request:

lhci assert on Meera's pull request, the first failureText
$ lhci assertChecking assertions against 2 URL(s), 10 total run(s) 5 result(s) for http://localhost:PORT/ :   ✘  largest-contentful-paint failure for maxNumericValue assertion       Largest Contentful Paint       https://developer.chrome.com/docs/lighthouse/performance/lighthouse-largest-contentful-paint/         expected: <=1300           found: 1511.0295      all values: 1511.0295, 1508.1439, 1503.2384, 1655.1388000000002, 1656.649
  • Line 2 says what it checked: 2 pages, 10 runs in all. Line 4 starts the Mint tea page's results.
  • Line 6 names the budget that failed. Lines 7 and 8 are its title and its docs.
  • Line 10 is the limit. Line 11 is the middle of the five runs. Line 12 lists all five, in the order they ran.

Every one of the five runs was over 1,300 ms. The page's bytes failed too: 103,485 against 26,000. Then lhci upload saved all 10 reports in lhci-reports/, with a list that marks each page's most typical run. Why it matters: two checks, measuring in two ways, both named Meera's picture.

Step 4: report on the pull request

The checks work. Now the answer has to reach Ben and Meera. GitHub Actions runs a workflow, a file of steps, on a fresh computer each time something happens in the repository. Ravi's workflow has one job. Here it is, in four parts.

performance.yml, part 1: when it runs, and what it may doYAML
name: Performanceon:  pull_request:    branches: [main] permissions:  contents: read  pull-requests: write
  • Line 1 names the workflow.
  • Lines 2 to 4 run it on pull requests into main. GitHub's docs say this runs when a pull request is opened or reopened, and each time its branch gets new commits.
  • Lines 6 to 8 set what the job's token may do. GitHub makes a fresh token, GITHUB_TOKEN, for every job. This one may read the code and write to pull requests, which includes commenting on them. Every permission not listed is set to none.
performance.yml, part 2: the machine and the size checkYAML
jobs:  budgets:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: actions/setup-node@v7        with:          node-version: 22      - name: Check every file's size        run: node scripts/check-size.mjs
  • Line 2 names the job budgets. Line 3 asks GitHub for a fresh Linux computer, called a runner.
  • Line 5 fetches the code. For a pull request, GitHub's docs say this is the branch merged into main. So the check tests what main will be after the merge.
  • Lines 6 to 8 install Node.js 22. Lines 9 and 10 run the size check.
performance.yml, part 3: Lighthouse CIYAML
      - name: Run Lighthouse 5 times on each page        if: ${{ !cancelled() }}        run: npx --yes @lhci/cli@0.16.1 collect      - name: Check each page's medians        if: ${{ !cancelled() }}        run: npx --yes @lhci/cli@0.16.1 assert      - name: Save the reports        if: ${{ !cancelled() }}        run: npx --yes @lhci/cli@0.16.1 upload
  • Lines 3, 6 and 9 run Lighthouse CI's three commands. npx --yes fetches the package and runs it, and @0.16.1 pins the version, so every run uses the same Lighthouse.
  • Line 2, and lines 5 and 8, say if: ${{ !cancelled() }}. Normally a step runs only if every step before it passed. This runs it anyway, unless someone cancelled the workflow. So when the size check fails, Lighthouse still runs, and the report shows everything.

The ! means "not". GitHub's docs say an if that starts with ! must be wrapped in ${{ }}, because YAML gives ! a meaning of its own.

performance.yml, part 4: the report, the comment and the reportsYAML
      - name: Write the report        if: ${{ !cancelled() }}        run: |          node scripts/report.mjs > report.md          cat report.md >> "$GITHUB_STEP_SUMMARY"      - name: Comment on the pull request        if: ${{ !cancelled() }}        continue-on-error: true        run: gh pr comment "$PR" --body-file report.md --edit-last --create-if-none        env:          GH_TOKEN: ${{ github.token }}          PR: ${{ github.event.pull_request.html_url }}      - name: Keep the Lighthouse reports        if: ${{ !cancelled() }}        uses: actions/upload-artifact@v7        with:          name: lighthouse-reports          path: lhci-reports
  • Line 4 writes the report to report.md. Line 5 adds it to the job summary: GitHub shows the Markdown in the file $GITHUB_STEP_SUMMARY on the run's page.
  • Line 9 posts the same report as a comment, with GitHub's own command line tool, gh. Every runner GitHub hosts has it. --edit-last edits the last comment GitHub Actions wrote there, and --create-if-none writes the first one. So the pull request keeps one comment, updated on each push.
  • Line 8, continue-on-error: true, keeps a failed comment from failing the job. Lines 11 and 12 give gh the token and the pull request's address.
  • Lines 13 to 18 keep the Lighthouse reports with the run, as a download called an artifact.

Before committing, Ravi checks the file with actionlint, a checker for workflow files. It ran ShellCheck on the run: lines too, and found no errors. A typo in a workflow file is easy to miss, because nothing runs it until the next pull request.

The report

scripts/report.mjs reads size-report.json and Lighthouse CI's results file, then writes Markdown. Its heading comes from four lines:

report.mjs: the headingJavaScript
const failedFiles = sizes.filter((row) => !row.passed);const failedPages = lighthouse.filter((row) => !row.passed);const failed = failedFiles.length + failedPages.length;const lines = [failed === 0 ? "## Performance budgets: all passed" : `## Performance budgets: ${failed} failed`, ""];

Lines 1 and 2 keep the files and the page budgets that failed. Line 3 counts them. Line 4 makes the heading: all passed, or how many failed. Then come a table of every page budget, a table of the files that failed, and each failed budget's reason. Here is the comment Meera got:

The comment on Meera's pull requestMarkdown
## Performance budgets: 3 failed ### Lighthouse, the median of 5 runs on a phone | Page | Budget | Median | Limit | Result || --- | --- | ---: | ---: | --- || `/` | largest-contentful-paint | 1,511 | 1,300 | **over** || `/` | total-blocking-time | 119 | 200 | pass || `/` | cumulative-layout-shift | 0.000 | 0.100 | pass || `/` | resource-summary:total:size | 103,485 | 26,000 | **over** || `/` | resource-summary:third-party:count | 0 | 0 | pass || `/finder/` | largest-contentful-paint | 1,657 | 1,700 | pass || `/finder/` | total-blocking-time | 0 | 100 | pass || `/finder/` | cumulative-layout-shift | 0.000 | 0.100 | pass || `/finder/` | resource-summary:total:size | 80,053 | 89,000 | pass || `/finder/` | resource-summary:third-party:count | 0 | 0 | pass | ### Files, in gzip bytes | File | gzip | Brotli | Budget | Result || --- | ---: | ---: | ---: | --- || `hero.svg` | 77,756 | 66,481 | 1,100 | **over** | ### Why these budgets - `hero.svg`: Main sends 993 bytes. The LCP picture. With the textured one, LCP was 6.5 s in lesson 45.1.- `/ largest-contentful-paint`: Main's slowest of 15 runs: 1,256 ms, rounded up. Lesson 45.1 cut this page's LCP from 6.5 s to 1.3 s.- `/ resource-summary:total:size`: Main's page sends 23,274 bytes in all, plus a tenth.

Line 1 is the verdict. The first table is each page's middle run against its limit. The second is the one file that failed. The last part is each failure's reason, copied from budgets.json. Ben's comment began ## Performance budgets: all passed. It had the same page table, and one line saying all 12 files were within their budgets.

Four budgets on each pull request: the file the change touched, then three of the Mint tea page's. Ben's: all 22 budgets passed. app.js gzip 12,936 against 14,200, within; LCP, ms 1,202 against 1,300, within; page bytes 23,300 against 26,000, within; TBT, ms 96 against 200, within. Meera's: 3 of 22 budgets failed. hero.svg gzip 77,756 against 1,100, over; LCP, ms 1,511 against 1,300, over; page bytes 103,485 against 26,000, over; TBT, ms 119 against 200, within.The answers on the two pull requestsBen's PRall 22 budgets passedapp.js gzip12,936 / 14,200LCP, ms1,202 / 1,300page bytes23,300 / 26,000TBT, ms96 / 200Meera's PR3 of 22 budgets failedhero.svg gzip77,756 / 1,100LCP, ms1,511 / 1,300page bytes103,485 / 26,000TBT, ms119 / 200
Four budgets on each pull request, from the course's recording: the file each change touched, then three of the Mint tea page's. Ben's change grew app.js a little and stayed inside every budget. Meera's picture broke three: its own size, the page's bytes and its LCP.
Real-life analogyA restaurant's inspection sticker, and the full report

After an inspection, a restaurant puts a sticker in its window: passed or failed. Anyone walking by sees it at once. The owner also gets the full report, with each problem and the rule it broke. The sticker says whether to worry. The report says what to fix.

In real life: The sticker in the window: pass or fail
In web performance: The check on the pull request
In real life: A town rule: no sticker, no opening
In web performance: A required check: no merge until it passes
In real life: The inspector's full report
In web performance: The comment and the job summary
In real life: The rulebook the inspector used
In web performance: budgets.json, with a reason for each budget

What GitHub does with it

  • The check: GitHub Actions shows each job on the pull request as a check, with its pass or fail. Meera's budgets check failed, because two of its steps ended with exit code 1.
  • A required check: in the repository's settings, a branch protection rule can require the check to pass before anyone merges into main. GitHub's docs warn that a skipped job counts as passed, so don't put an if on the whole job.
  • The job summary: each step's summary can hold up to 1 MiB of Markdown. It shows on the run's page, whatever happens to the comment.
  • Pull requests from forks: a fork is someone else's copy of the repository. For their pull requests, GitHub gives the token read-only permissions. The comment step fails, continue-on-error lets the job go on, and the check and the summary still work.

Why it matters: the check stops the merge, and the comment says why, with numbers and reasons. When Meera pushes a lighter picture, the workflow runs again, and the same comment changes to the new answer.

Which check catches it?

The course ran six more changes through the pipeline. Each one replays a problem the store has had, or could have. Sort each change, and Meera's picture, by what caught it in the recording:

Which check catches it?
  • Meera's picture, with its 14,000-dot texture
  • A lighter texture: 300 of the dots
  • All of Swiper, for a carousel
  • No room kept for the late promotion
  • The chat widget's script on every load
  • app.js in the head without defer
  • Add to cart redraws every tea
Try it yourself
0 of 7 correct

Sort each change by the check that failed it in the course's recording.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

The last kind matters most. Lighthouse loads a page; it doesn't tap. A slow tap passes every check here. Lesson 45.2's weekly alert on the field's INP is the check that sees it.

Common mix-ups

  • "A budget should be Google's good line." No. The Mint tea page's LCP could almost double and still be under 2,500 ms. A budget sits just above where you are today.
  • "If both checks pass, nothing got worse." No. With app.js in the head without defer, the first paint came at 904 ms instead of 757. LCP didn't move, and no budget measured the first paint.
  • "Lighthouse CI catches slow taps." No. It loads the page and doesn't tap. The slow Add button passed every budget.
  • "A file that isn't in budgets.json is free." No. The size check fails it, so every new file comes with a budget and a reason.
  • "The middle of five runs makes any check steady." No. It hides one or two odd runs. On the finder, where runs fell into two groups, the middle run moved from job to job.
  • "The workflow needs write access to everything." No. It reads the code and writes to pull requests. Every permission you don't list is set to none.

Practice exercises

Answer first, then use the hints. Some use the playground, one uses a published file, and one uses a published report.

Exercise 1 · Warm-upA budget for a new file

Meera's next pull request adds an icon sprite. What budget does the rule give it?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// Meera's next pull request adds icons.svg: 2,345 bytes with gzip
const fileBudget = (gzip) => Math.ceil((gzip * 11) / 1000) * 100;
console.log(fileBudget(2345));

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upThe middle of Meera's runs

    These are the Mint tea page's five LCPs in Meera's second job. What does it print?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // The Mint tea page's LCP in Meera's second job: five runs, in ms
    const lcps = [1506.6, 1504.7, 1654, 1503.8, 1505.9];
    const middle = [...lcps].sort((a, b) => a - b)[2];
    console.log(`middle: ${middle}, ${middle <= 1300 ? "within" : "over"} the budget`);

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeNo room at all

      In the playground, set the room to 0%. How many of the changes that are fine fail?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeThe catalogue's budget

        Open budgets.json. What is the gzip budget for finder/teas.json, in bytes?

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeThe picture in Meera's report

          Download Meera's Mint tea page report, and open it in the Lighthouse Viewer. What transfer size does it give for hero.svg?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeReady for review

            Ben opens his pull requests as drafts. Which activity type runs the workflow when he marks one ready for review?

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask which check would see the problem, and how many runs it reads.

              The performance pipeline quiz · 8 questionsScore: first tries count
              1. Question 1 of 8A pull request adds site/vendor/chart.js, and nobody adds it to budgets.json. What does check-size.mjs do?

                Choose an answer to see the explanation.

              2. Question 2 of 8Why does lighthouserc.cjs read its limits from budgets.json, instead of holding its own?

                Choose an answer to see the explanation.

              3. Question 3 of 8Why do the Lighthouse steps say if: ${{ !cancelled() }}?

                Choose an answer to see the explanation.

              4. Question 4 of 8Why does the comment step have continue-on-error: true?

                Choose an answer to see the explanation.

              5. Question 5 of 8The workflow lists contents: read and pull-requests: write. What may its token do with the repository's issues?

                Choose an answer to see the explanation.

              6. Question 6 of 8What does this rule program print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                const timeBudget = (slowest) => Math.ceil(slowest / 100) * 100;
                console.log(timeBudget(1200), timeBudget(1200.1));

                Choose an answer to see the explanation.

              7. Question 7 of 8app.js without defer passed both checks, though the first paint came later. What would have caught it?

                Choose an answer to see the explanation.

              8. Question 8 of 8Which check would catch a slow Add to cart button?

                Choose an answer to see the explanation.

              Key takeaways

              • Measure main the way the check will, then set each budget just above its slowest run, with a reason.
              • Keep every budget in one file. Both checks read it, and the report quotes its reasons.
              • Check every file's gzip size, and fail any file with no budget.
              • Run Lighthouse CI five times on each page, and judge each budget by the middle run.
              • Let the job fail the check, fill the job summary, and keep one comment up to date, with only the permissions it needs.
              • A lab check can't tap. Keep watching INP in the field.

              Remember the one-liner.
              Write each budget down with its reason, check every file and every page on each pull request, and put the answer where the author looks.

              Sources

              The facts on this page come from these docs and source files:

              Coming next: Project: instant navigations. You'll make the store's pages open at once, with the back/forward cache, Speculation Rules and view transitions.

              CompleteFrontend Clear concepts. Working examples.