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.
- 01Choose budgets from your own numbersMeasure main the way the check will, leave room above the wobble, and write each budget down with its reason.
- 02Check 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.
- 03Put 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 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.
gzipis the file's size in bytes once it's packed for sending, andbudgetis its limit.lcpis 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 budgetandmeera/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 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
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:
- budgets.json: every budget, with its reason (step 1).
- scripts/check-size.mjs: the size check (step 2).
- lighthouserc.cjs: Lighthouse CI's settings (step 3).
- .github/workflows/performance.yml: the workflow (step 4).
- scripts/report.mjs: the report for the summary and the comment (step 4).
- .gitignore: the files the checks write, kept out of git.
- Ben's comment: the report on his pull request.
- Meera's comment: the report on hers.
- Meera's size check: what check-size.mjs printed.
- Meera's lhci assert: what Lighthouse CI's assert step printed.
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
mainwith no limits, for the budgets. Then three rounds ofmain, 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 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 1300andhero.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.
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:
{ "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.
| Budget | What did main have? | The limit | Why this limit? |
|---|---|---|---|
| Mint tea page, LCP | 1,199 to 1,256 ms | 1,300 ms | 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. |
| Mint tea page, TBT | 94 to 103 ms | 200 ms | Main's slowest of 15 runs: 103 ms, rounded up. Lighthouse doesn't tap, so this stands in for INP. |
| Mint tea page, all bytes | 23,274 bytes | 26,000 bytes | Main's page sends 23,274 bytes in all, plus a tenth. |
| Tea finder, LCP | 753 to 1,668 ms | 1,700 ms | Main's slowest of 15 runs: 1,668 ms, rounded up. Google's good line is 2,500 ms. |
hero.svg, gzip | 993 bytes | 1,100 bytes | Main sends 993 bytes. The LCP picture. With the textured one, LCP was 6.5 s in lesson 45.1. |
app.js, gzip | 12,904 bytes | 14,200 bytes | Main 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:
- 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
- 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
- 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
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.
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: 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.jsonand keeps itsfilespart. - Lines 6 to 8 list every file in
site/, in folders too, likefinder/app.js. They keep files, not folders, in order.
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?? nullgivenullwhen the file has none. - Line 6 passes a file only if it has a budget and its gzip size fits.
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
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:
$ 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:
$ 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 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
pagespart ofbudgets.json. A.cjsfile can load JSON withrequire(). - 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.maxNumericValueis 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 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:
// 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.2andbest 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).
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 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.
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.
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 whatmainwill be after the merge. - Lines 6 to 8 install Node.js 22. Lines 9 and 10 run the size check.
- 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 --yesfetches the package and runs it, and@0.16.1pins 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.
- 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_SUMMARYon 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-lastedits the last comment GitHub Actions wrote there, and--create-if-nonewrites 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 giveghthe 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:
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:
## 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.
app.js a little and stayed inside every budget. Meera's picture broke three: its own size, the page's bytes and its LCP.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
budgetscheck 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 anifon 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-errorlets 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:
- 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
Sort each change by the check that failed it in the course's recording.
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.jsin the head withoutdefer, 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.
Meera's next pull request adds an icon sprite. What budget does the rule give it?
// 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));2600. 2,345 × 1.1 is 2,579.5, and the next 100 up is 2,600. Meera adds that budget to budgets.json in the same pull request.
These are the Mint tea page's five LCPs in Meera's second job. What does it print?
// 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`);middle: 1505.9, over the budget. Every run was over the limit, so even the best run would have failed.
In the playground, set the room to 0%. How many of the changes that are fine fail?
5 of 6. With no room, any job a little slower than main's slowest run fails, and so does Ben's slightly bigger app.js.
Open budgets.json. What is the gzip budget for finder/teas.json, in bytes?
71,900 bytes: main's 65,322, plus a tenth, rounded up to the next 100.
Download Meera's Mint tea page report, and open it in the Lighthouse Viewer. What transfer size does it give for hero.svg?
79.7 KiB, which is 81,573 bytes. It isn't the size check's 77,756: Lighthouse CI's own server packs files with Brotli at a low level, 4, and the count includes the response's headers. Compare each tool's bytes only with the same tool's.
Ben opens his pull requests as drafts. Which activity type runs the workflow when he marks one ready for review?
on:
pull_request:
branches: [main]
types: [opened, synchronize, reopened, ready_for_review]ready_for_review. Listing types replaces the defaults, so keep opened, synchronize and reopened as well.
Check your understanding
For each question, ask which check would see the problem, and how many runs it reads.
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.
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.
Question 3 of 8Why do the Lighthouse steps say
if: ${{ !cancelled() }}?Choose an answer to see the explanation.
Question 4 of 8Why does the comment step have
continue-on-error: true?Choose an answer to see the explanation.
Question 5 of 8The workflow lists
contents: readandpull-requests: write. What may its token do with the repository's issues?Choose an answer to see the explanation.
Question 6 of 8What does this rule program print?
Read the code, then predictconst timeBudget = (slowest) => Math.ceil(slowest / 100) * 100; console.log(timeBudget(1200), timeBudget(1200.1));Choose an answer to see the explanation.
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.
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:
- Lighthouse CI: Configuration (0.16.1), Google Chrome on GitHub.
- Lighthouse CI: assertions.js (0.16.1), Google Chrome on GitHub.
- Lighthouse Variability, Google Chrome on GitHub.
- compression: index.js (1.8.2), the server middleware Lighthouse CI uses, Express on GitHub.
- zlib Manual: deflateInit, zlib.
- Brotli: encode.h, Google on GitHub.
- Content-Encoding, MDN.
- Events that trigger workflows: pull_request, GitHub Docs.
- Workflow syntax for GitHub Actions, GitHub Docs.
- Evaluate expressions: status check functions, GitHub Docs.
- Workflow commands: adding a job summary, GitHub Docs.
- Use GITHUB_TOKEN for authentication in workflows, GitHub Docs.
- Using GitHub CLI in workflows, GitHub Docs.
- gh pr comment, GitHub CLI manual.
- Permissions required for GitHub Apps: pull requests, GitHub Docs.
- About status checks, GitHub Docs.
- About protected branches: require status checks before merging, GitHub Docs.
- actionlint, rhysd on GitHub.
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.