Per-Template Performance Budgets

A performance budget that covers "the site" usually means a budget for the home page, because that is the URL someone put in the Lighthouse CI config. Meanwhile, the pages readers actually land on — articles, docs pages, product pages, tag archives — each come from a different template with different weight and different failure modes. A new component added to the article template can double its JavaScript without touching the home page, and the budget stays green.

This guide sets up budgets per template on a static site with seven templates: choosing representative URLs automatically from the build, setting limits based on each template's purpose and measured baseline, enforcing them with Lighthouse CI assertions and a deterministic size check, and reporting results per template in pull requests. It is part of Performance Budgets and Lighthouse CI, and extends Writing a Performance Budget That Fails Builds.

Prerequisites

• A static site built in CI, with a local server or preview deploy for Lighthouse CI.
• Lighthouse CI (@lhci/cli) 0.13+.
• Knowledge of which layout or template renders each page — available from frontmatter or the build output.

Step 1: Inventory Templates and Their Traffic

The site — a product's marketing pages, docs and blog, built with Astro — had seven templates. Field data showed which mattered most:

The previous budget covered only the home page — 9% of landings. The blog template had regressed from 1.5 s to 1.9 s over three months without any budget noticing.

Step 2: Pick Representative URLs From the Build

Hard-coded URL lists go stale. The build writes a manifest of one typical and one worst-case page per layout, chosen by rules: the typical page is the median by HTML size, the worst case is the largest by total referenced image and script bytes.

// scripts/budget-urls.mjs — runs after the build
const pages = await readBuiltPages('dist');                 // [{ url, layout, htmlBytes, assetBytes }]
const byLayout = groupBy(pages, (p) => p.layout);
const manifest = Object.entries(byLayout).map(([layout, list]) => {
  const sorted = [...list].sort((a, b) => a.htmlBytes - b.htmlBytes);
  const typical = sorted[Math.floor(sorted.length / 2)];
  const worst = [...list].sort((a, b) => b.assetBytes - a.assetBytes)[0];
  return { layout, urls: [...new Set([typical.url, worst.url])] };
});
await writeFile('budget-urls.json', JSON.stringify(manifest, null, 2));

The layout name comes from a data-layout attribute each layout writes on <body>. A new template automatically enters the manifest the next time the build runs, and CI fails if a layout has no budget defined — which forces a conscious decision about every new template.

Step 3: Set Limits per Template

Budgets start from the measured baseline and the template's purpose, then tighten. For each template:

LCP is measured in the calibrated profile from Performance Testing on Throttled Mobile Profiles. Sizes are compressed transfer sizes. CLS is 0.05 for every template.

Lighthouse CI supports per-URL assertions with assertMatrix, which maps URL patterns to assertion sets:

// lighthouserc.cjs
const manifest = require('./budget-urls.json');
const budgets = require('./budgets.json');   // the table above, keyed by layout
module.exports = { ci: {
  collect: { url: manifest.flatMap((m) => m.urls.map((u) => `http://localhost:4321${u}`)), numberOfRuns: 3 },
  assert: { assertMatrix: manifest.map(({ layout, urls }) => ({
    matchingUrlPattern: urls.map((u) => u.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'),
    assertions: {
      'largest-contentful-paint': ['error', { maxNumericValue: budgets[layout].lcp }],
      'total-blocking-time': ['error', { maxNumericValue: budgets[layout].tbt }],
      'cumulative-layout-shift': ['error', { maxNumericValue: 0.05 }],
      'resource-summary:script:size': ['error', { maxNumericValue: budgets[layout].js * 1024 }],
      'resource-summary:image:size': ['warn', { maxNumericValue: budgets[layout].img * 1024 }],
      'resource-summary:third-party:count': ['error', { maxNumericValue: budgets[layout].thirdParty }]
    }
  })) }
} };

Step 4: Add a Deterministic Size Check

Timing metrics vary between runs even with care; sizes do not. A second check reads the built HTML for each manifest URL, resolves every referenced script, stylesheet and image in the initial HTML, sums their compressed sizes from the build output, and compares with the same budgets. It runs in about four seconds without a browser, catches byte regressions exactly, and posts the per-template diff on the pull request alongside the bundle-size report from Tracking Bundle Size per Pull Request. Lighthouse then judges the timing metrics, where its three-run median is stable enough to gate on.

Step 5: Report Per Template

A pull request comment shows each template's numbers against its budget, with the change from the base branch:

Template          LCP     TBT    JS      CSS    Img     3P
docs-article      1.52s   60ms   44KB    11KB   180KB   1   ✅
blog-post         1.71s   40ms   38KB    11KB   420KB▲  2   ⚠ images +62KB
landing           2.05s   130ms  71KB    14KB   310KB   3   ✅

Reviewers see immediately which template a change affected, which is the point of per-template budgets. The blog regression that had gone unnoticed would have appeared as a warning on the pull request that introduced a new author-card image component.

Negotiating Budgets With Designers and Marketers

Per-template budgets make trade-offs explicit, which is useful and occasionally uncomfortable. When the landing page template needed a video background for a campaign, the budget table made the conversation concrete: the video poster fits the image budget, the video itself loads only after interaction or when idle, and the third-party request count cannot grow, so the video is self-hosted rather than embedded from a platform. The budget did not say no; it shaped how the feature was built. Recording each budget change with a reason in the budgets file — "landing images 300 KB to 350 KB: campaign hero at 2x density, approved 2026-05" — turned the file into a history of deliberate decisions rather than a list of numbers that crept upward.

Measured Impact

Pitfalls & Rollback

• Hard-coded URL lists. They go stale; generate them from the build.
• One budget for everything. Complex templates fail constantly or simple ones are never checked.
• Gating on single Lighthouse runs. Use medians of several runs, and gate bytes deterministically.
• Budgets nobody updates. Revisit after intentional design changes, and record why a budget moved.
• Rollback: the manifest and assertion matrix are CI configuration; switching assertions to warn or restoring the single-URL config removes the gate immediately.

Conclusion

Readers land on templates, not on "the site". Pick representative pages per template automatically from the build, set budgets that match each template's purpose, enforce timings with Lighthouse CI's assertion matrix and bytes with a deterministic check, and show results per template in every pull request. On this site that took budget coverage from 9% of landing traffic to 99% and caught fourteen regressions in six months.

FAQ

Why budget per template instead of per site?

Templates differ in what they need. A landing page with a hero image and a documentation page with code blocks have different reasonable limits for image bytes, JavaScript and LCP. A single site-wide budget is either too loose for simple templates or too strict for complex ones, and regressions hide in the average.

How many URLs per template should be tested?

One or two representative URLs per template usually suffice, since pages of the same template share their structure. Add a worst-case URL for templates whose content varies a lot, such as the longest article or the page with the most images.

What should a template budget include?

Metrics such as LCP, CLS and Total Blocking Time from Lighthouse, plus resource sizes and counts per type, such as JavaScript bytes, CSS bytes, image bytes and third-party requests. Size budgets are deterministic and catch regressions that timing metrics blur.

How do I keep the URL list current as the site changes?

Generate it from the build. Each template can mark one of its pages as representative in frontmatter, or a script can pick the first page per layout from the built output, so new templates get budgets automatically.

Related

• Parent: Performance Budgets and Lighthouse CI — budgets and CI in general.
• Setting Up Lighthouse CI for a Static Site — the base setup.
• Tracking Page Weight Over Time — the long-term view of the same numbers.
• Auditing Font Payload per Page — a per-template budget for fonts.
• Snapshot Testing Build Output — structural checks alongside size checks.