Your First Performance Budget With Lighthouse

Why Performance Becomes a Feature

In the modern web development landscape, performance is no longer an afterthought or a nice-to-have optimization--it has evolved into a fundamental feature that directly impacts user experience, search engine rankings, and business outcomes. As websites grow increasingly complex with interactive features, third-party integrations, and rich media content, the temptation to add "just one more script" or "a few more images" becomes a constant pressure that can silently degrade the user experience. This is where performance budgets step in as your systematic defense against gradual performance decay.

A performance budget is essentially a set of limits you establish to prevent performance regressions from sneaking into your codebase. Think of it as a financial budget for your website's resource consumption--when you spend too much on heavy JavaScript bundles or high-resolution images, you risk running into the same problems that cause users to abandon your site and never return. Lighthouse, Google's comprehensive auditing tool, provides the perfect framework for implementing and enforcing these budgets as part of your development workflow.

The concept of a performance budget transforms performance from an abstract concern discussed during sprint planning into concrete, measurable constraints that developers can see and respect every time they push code. When performance budgets are integrated into your continuous integration pipeline, they become an automated gatekeeper that prevents performance regressions before they ever reach production. This proactive approach is far more effective than discovering performance issues after users start complaining or after your search engine rankings begin to slip.

Understanding how to properly implement performance budgets with Lighthouse requires familiarity with several interconnected concepts: the Core Web Vitals metrics that Google uses to measure user-perceived performance, the various types of budgets you can establish, and the technical implementation through Lighthouse CI. This guide will walk you through each of these areas, providing you with the knowledge and practical tools needed to establish your first performance budget and maintain it over time.

Understanding Performance Budget Fundamentals

The Three Pillars of Performance Budgets

Performance budgets can be categorized into three fundamental types, each addressing a different aspect of your website's resource consumption. Understanding these categories is essential because they each serve distinct purposes and can be used together to create a comprehensive performance strategy that covers all critical areas of your site's resource usage.

Timing-based budgets directly constrain the Core Web Vitals and other performance metrics that users actually experience. These budgets set maximum thresholds for metrics like Largest Contentful Paint (LCP), which measures how quickly the main content becomes visible, First Input Delay (FID) or Interaction to Next Paint (INP) for responsiveness, and Cumulative Layout Shift (CLS) for visual stability. Timing-based budgets translate abstract performance concepts into concrete numbers that can be automatically checked during development or deployment. For example, you might establish a budget requiring that LCP never exceed 2.5 seconds on mobile devices, ensuring that your users always see meaningful content quickly.

Quantity-based budgets limit the number or size of specific resource types loaded by your pages. These budgets operate on the raw data level, constraining things like the total JavaScript bundle size in kilobytes, the number of HTTP requests per page, the combined weight of all images, or the size of third-party scripts. Quantity-based budgets are often easier to establish initially because they require simple measurements rather than complex timing analysis. A typical quantity-based budget might limit total JavaScript to 200KB, images to 1MB, and total requests to 50 per page. These constraints directly impact timing metrics but are measured at the resource level rather than the experience level.

Rule-based budgets enforce specific Lighthouse audit requirements or minimum category scores. These budgets ensure that your site maintains minimum standards across Lighthouse's various auditing categories, including performance, accessibility, best practices, and SEO. Rule-based budgets might require that the performance category never fall below 90, that all accessibility audits pass, or that certain critical best practices are always followed. These budgets provide guardrails that keep your site aligned with industry standards and Google's evolving requirements.

Connecting Budgets to Business Outcomes

The true power of performance budgets lies in their connection to measurable business outcomes rather than purely technical metrics. Research consistently shows that faster websites convert better, retain users longer, and rank higher in search results. When establishing your initial budgets, you should consider what performance thresholds correlate with positive business outcomes for your specific situation. For an e-commerce site, this might mean ensuring that checkout pages load quickly enough to prevent cart abandonment. For a content site, it might mean keeping article pages fast enough to reduce bounce rates and increase engagement metrics.

Setting realistic budgets requires understanding your current performance baseline and your users' actual conditions. The budgets you set should be challenging enough to drive continuous improvement but achievable enough that they don't become frustrating obstacles to development progress. A common approach is to start with budgets that reflect your current 75th percentile performance--meaning 75% of your pages already meet the budget--and then gradually tighten them over time as your team improves its performance culture and optimization capabilities.

Establishing budgets with both warning and error thresholds provides flexibility while maintaining accountability. A warning threshold might trigger a notification or log message when exceeded, allowing developers to address the issue before merging, while an error threshold would fail the build entirely and block deployment. This two-tiered approach prevents minor exceedances from blocking development while ensuring that significant regressions are caught before reaching production.

Setting Up Lighthouse CI for Budget Management

Installing and Configuring the Lighthouse CI CLI

Lighthouse CI provides a suite of tools that facilitate using Lighthouse for continuous performance monitoring. Unlike the standard Lighthouse CLI, which provides single-run audits, Lighthouse CI is designed specifically for tracking performance changes over time and integrating into automated workflows. The core functionality comes through the Lighthouse CI command line interface, which offers commands for running multiple Lighthouse analyses, identifying median results, and uploading reports for storage and comparison.

To get started with Lighthouse CI, you'll first need to install the CLI globally via npm:

npm install -g @lhci/cli

After installation, Lighthouse CI requires a configuration file, typically named lighthouserc.js, placed in the root of your project repository. This file is mandatory and contains all the configuration information for how Lighthouse CI should operate, including which URLs to test, how many runs to perform, and how to handle assertions and uploads.

The basic structure of the configuration file includes sections for collecting performance data, asserting against budgets, and uploading results for storage. Here's the minimal configuration structure:

module.exports = {
 ci: {
 collect: {
 // Collection settings go here
 },
 assert: {
 // Assertion/budget settings go here
 },
 upload: {
 // Upload and storage settings go here
 },
 },
};

Each of these sections can be customized extensively to match your specific workflow requirements. The collect section controls how Lighthouse runs are executed, including the URLs to test, number of runs, and how to start your local server for testing. The assert section defines your performance budgets and the thresholds at which builds should pass or fail. The upload section determines where your Lighthouse reports should be stored and how they should be made available for review.

Configuring Collection Settings

The collection settings in your Lighthouse CI configuration determine how performance data is gathered. Every time Lighthouse CI runs, it needs to start a server to serve your website so that Lighthouse can load and analyze your pages. For static sites, you can specify the directory containing your built files using the staticDistDir property:

collect: {
 staticDistDir: './public',
}

For dynamic sites that require a running application server, you'll use the startServerCommand property instead to specify the command that starts your development or production server:

collect: {
 startServerCommand: 'npm run start',
}

Lighthouse CI will automatically start the server before running audits and shut it down afterward, ensuring a clean testing environment for each run. You'll also need to specify which URLs Lighthouse should audit by adding a url property with an array of URLs:

collect: {
 url: ['http://localhost:8080'],
}

By default, Lighthouse CI will run Lighthouse three times against each URL and use the median result to reduce variance from network conditions or other transient factors. You can adjust this using the numberOfRuns property if you want more runs for increased stability or fewer runs for faster feedback:

collect: {
 numberOfRuns: 5,
}

Running Lighthouse CI locally using the lhci autorun command is the best way to verify your configuration before integrating it into your CI/CD pipeline. This command executes multiple Lighthouse runs, identifies the median report, and uploads it to temporary public storage for review.

Creating Your First Performance Budget File

Understanding the Budget.json Format

Performance budgets for Lighthouse are defined in a separate JSON file, conventionally named budget.json. This file contains an array of budget objects, each specifying resource constraints that apply to matching pages. The budget file supports two primary constraint types: resourceSizes for limiting the byte size of specific resource categories, and resourceCounts for limiting the number of resources loaded.

The budget file structure consists of an array where each element is a budget object with optional path matching:

[
 {
 "path": "/*",
 "resourceSizes": [
 // Size budgets here
 ],
 "resourceCounts": [
 // Count budgets here
 ]
 }
]

The path property uses glob-style pattern matching to determine which pages a particular budget applies to. This allows you to define different budgets for different page types--for example, a lighter budget for mobile users, stricter limits for critical pages like checkout, or relaxed budgets for admin dashboards where performance is less critical. If the path is left blank or omitted, the budget applies to all pages. When multiple budgets match a page, the last matching budget in the file is used, allowing you to establish general rules with specific overrides.

Defining Resource Size Budgets

Resource size budgets constrain the total byte weight of specific resource categories. Each entry in the resourceSizes array specifies a resourceType and a budget value in kilobytes. Lighthouse supports the following resource types: document, font, image, media, script, stylesheet, other, third-party, and total.

Here's an example budget file with size constraints for a typical content site:

[
 {
 "path": "/*",
 "resourceSizes": [
 { "resourceType": "script", "budget": 200 },
 { "resourceType": "image", "budget": 800 },
 { "resourceType": "stylesheet", "budget": 100 },
 { "resourceType": "font", "budget": 100 },
 { "resourceType": "total", "budget": 1500 }
 ],
 "resourceCounts": [
 { "resourceType": "total", "budget": 50 }
 ]
 }
]

In this example, the total JavaScript across all scripts is limited to 200KB, images to 800KB, stylesheets to 100KB, fonts to 100KB, and the overall page weight to 1.5MB. The resourceCounts section adds a constraint limiting the total number of HTTP requests to 50 per page. These values would be appropriate for a desktop-focused site with moderate image content; mobile budgets might need to be more aggressive, while image-heavy sites might require larger image budgets but tighter constraints on other resource types. For comprehensive strategies on reducing your image footprint, see our guide on image optimization.

Configuring Assertions for Automated Budget Enforcement

Understanding Assertion Levels

Lighthouse CI's assertion system provides the mechanism for enforcing your performance budgets within automated workflows. Assertions can be configured at three levels, each with different behavior when budget thresholds are exceeded:

• off - The assertion is ignored entirely and never triggers
• warn - Failures are printed to standard error but do not stop the process; useful for tracking issues without blocking development
• error - Failures are printed to standard error and cause Lighthouse CI to exit with a non-zero status code, which will fail the build in CI/CD pipelines

The appropriate level depends on the criticality of the constraint and your team's workflow. For example, you might set category score minimums as error-level assertions that will fail the build, while individual resource budgets might start as warnings to avoid blocking development while the team works to optimize. As your team's performance culture matures, warnings can be upgraded to errors to ensure consistent adherence to budgets.

Setting Category Score Assertions

Category score assertions ensure that your site maintains minimum Lighthouse scores across different auditing categories. These assertions are particularly valuable because they provide a holistic view of site quality rather than focusing on individual metrics. Here's how to configure minimum score assertions:

assert: {
 assertions: {
 'categories:performance': ['error', { minScore: 90 }],
 'categories:accessibility': ['error', { minScore: 100 }],
 'categories:best-practices': ['warn', { minScore: 90 }],
 'categories:seo': ['warn', { minScore: 85 }]
 }
}

In this configuration, the performance and accessibility categories must maintain scores of 90 and 100 respectively, or the build will fail. The best-practices and SEO categories are set to warning level, alerting the team to regressions without blocking merges.

Setting Budget Assertions

Budget assertions enforce the constraints defined in your budget.json file. When a budget is exceeded, the assertion can trigger either a warning or an error depending on your configuration:

assert: {
 assertions: {
 'resource-summary:budget:url': ['error'],
 'resource-summary:budget:script': ['error'],
 'resource-summary:budget:third-party': ['warn']
 }
}

The assertion format for budget violations uses the resource-summary audit with budget identifiers. By setting the third-party budget to warning level, you can track when this constraint is exceeded without blocking merges, while total and script budgets are treated as hard requirements.

Integrating Lighthouse CI with GitHub Actions

Setting Up Your GitHub Workflow

GitHub Actions provides an excellent platform for running Lighthouse CI automatically on every code change. By configuring a workflow to run Lighthouse CI on pull requests, you can display performance results directly in the PR interface, making it easy for reviewers to see the performance impact of proposed changes before they're merged.

To set up GitHub Actions integration, first create a .github/workflows directory in your repository if it doesn't already exist. Then create a workflow file, typically named lighthouse-ci.yml:

name: Build project and run Lighthouse CI

on: [push]

jobs:
 lhci:
 name: Lighthouse CI
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Use Node.js
 uses: actions/setup-node@v4
 with:
 node-version: 20
 - name: Install dependencies
 run: |
 npm install
 npm install -g @lhci/cli
 - name: Build project
 run: npm run build
 - name: Run Lighthouse CI
 run: lhci autorun

This basic workflow checks out the code, sets up Node.js, installs dependencies including Lighthouse CI, builds the project, and runs Lighthouse CI.

Configuring Status Checks

GitHub status checks allow Lighthouse CI results to appear directly in the pull request interface, showing whether performance budgets passed or failed. To enable this, you'll need to set up the GitHub App integration by creating a GitHub App and installing it on your repository, or by using a personal access token for smaller projects.

For the status check to work properly, your Lighthouse CI configuration needs to include GitHub token authentication:

upload: {
 target: 'temporary-public-storage',
}

When a GitHub token is provided, Lighthouse CI will automatically post status checks to your pull requests showing the results of the Lighthouse run. This integration is particularly valuable because it brings performance feedback directly into the context where code changes are being reviewed, making it easy for team members to consider performance implications during the review process.

Sustaining Performance Budgets Over Time

Starting with Realistic Baselines

Establishing performance budgets that your team can actually maintain requires understanding your current performance reality and setting achievable targets. Before setting any budget values, run Lighthouse audits on several representative pages of your current site to establish baseline measurements. These baselines should cover different page types--homepage, content pages, product pages, checkout flows--as each will have different performance characteristics and appropriate budget levels.

When setting initial budget values, consider using your 75th percentile performance as a starting point. This means that 75% of your pages already meet the budget, making it achievable while still representing meaningful improvement for the remaining 25%. As your team becomes more performance-conscious and optimization becomes part of your regular workflow, you can gradually tighten the budgets to push for better performance across all pages.

Avoid the temptation to set aggressive budgets immediately. Unrealistic budgets that frequently fail create frustration and lead to teams ignoring the failures entirely. Instead, establish budgets that initially pass most of the time, then iterate toward stricter limits as your optimization capabilities improve. This approach builds performance culture gradually rather than forcing sudden changes that can create resistance.

Maintaining Budgets Over Time

Performance budgets require ongoing maintenance to remain relevant as your site evolves. New features, design changes, and third-party integrations can all impact performance, and your budgets need to be revisited periodically to ensure they still make sense for your current situation. Schedule regular budget reviews--quarterly at minimum--to assess whether current budgets are appropriate or need adjustment.

When adding new features or pages, establish budgets early in the development process rather than retrofitting them later. Including Lighthouse CI runs in your feature branch workflow helps catch performance issues before they reach the main branch. For major redesigns or new page types, consider creating separate budget entries that reflect the unique characteristics of these new components.

Track your performance trends over time using Lighthouse CI's reporting capabilities. The historical data helps identify gradual performance degradation that might not be apparent from individual runs, and it provides evidence for budget adjustments based on actual trends rather than guesses. If you notice that a particular budget is consistently exceeded by a small margin, consider adjusting the budget rather than ignoring the failures. Complement your budget strategy with minification and compression techniques to maximize resource efficiency.

Common Pitfalls and How to Avoid Them

Ignoring Third-Party Impact

One of the most common mistakes in performance budgeting is underestimating the impact of third-party scripts. Analytics tools, advertising platforms, social media widgets, and other external dependencies often load significant JavaScript and make additional requests that add up quickly. Many teams establish budgets without considering third-party resources, only to discover that external scripts consume a large portion of their performance budget.

To avoid this pitfall, always include third-party as a specific resource type in your budgets. Consider setting separate budgets for third-party script size and request count, and regularly audit which third-party services you're actually using. If a particular third-party service is consuming too much performance budget, evaluate whether its value justifies the performance cost or whether lighter alternatives exist.

Setting Budgets Without Measurement Context

Another common error is setting budget values without understanding what they actually mean in practice. A 200KB JavaScript budget sounds reasonable until you realize it allows for multiple large framework bundles that would significantly impact load time. Always validate your budget values against real Lighthouse runs to ensure they represent meaningful performance constraints rather than arbitrary numbers.

When setting size-based budgets, consider the implications for your specific technology stack. A React application might naturally have larger JavaScript bundles than a static HTML site, and budgets should reflect these realities. Similarly, image-heavy sites will naturally have higher image budgets than text-focused sites. The goal is to constrain growth and prevent unnecessary bloat, not to impose unrealistic limits that can't be followed.

Forgetting to Update Budgets for New Page Types

As websites grow, they often develop new page types with different performance characteristics. Interactive dashboards, web applications, and specialized feature pages might require different budget approaches than traditional content pages. Failing to account for these differences can lead to either overly strict budgets that block development on new features or overly loose budgets that don't provide meaningful constraints.

Use the path-matching capability of budget.json to create appropriate budgets for different page types. Dashboard pages might have different constraints than marketing pages. Product pages with rich media might have different image budgets than blog posts. This granular approach ensures each page type has appropriate constraints without forcing one-size-fits-all rules that don't match reality. Implementing lazy loading strategies can help manage resource loading on media-heavy pages.

Sources

1. MDN Web Docs: Performance Budgets - Foundational concepts of performance budgets, budget types, and measurement approaches.
2. Google Lighthouse CI Documentation - CI/CD integration, budget assertions, and configuration options.
3. Web.dev Lighthouse CI Guide - Step-by-step setup, GitHub Actions integration, and assertion configuration.
4. A Faster Web: Performance Budgets Guide - budget.json format and practical examples.