Documentation

Performance budgets

Set thresholds for LCP, INP, CLS, JavaScript bundle size, image weight, and route speed. Alert Slack, send webhooks, or fail CI on breach.

Performance budgets are hard limits on metrics that matter. When a budget is breached, PagePulse can trigger a Slack alert, send a webhook, file a Linear or Jira ticket, or fail a CI check. This guide covers how to define budgets, how they are evaluated, and how to enforce them in CI.

Defining a budget

Use PagePulse.setBudget to define one or more budgets. Budgets are evaluated against the 75th percentile of real-user traffic over the trailing 24 hours, refreshed every 5 minutes.

typescript

PagePulse.setBudget({
  // Core Web Vitals
  lcp: 2500,         // ms, target under 2.5s
  inp: 200,          // ms, target under 200ms
  cls: 0.1,          // score, target under 0.1
  ttfb: 800,         // ms, target under 800ms
  fcp: 1800,         // ms, target under 1.8s

  // Asset budgets
  jsSizeKB: 180,     // first-party + third-party JS
  imageSizeKB: 500,  // total image weight per route
  cssSizeKB: 50,     // total CSS weight per route

  // Timing budgets
  routeLoadMs: 1000, // time to load a route
  hydrationMs: 800,  // React/Vue hydration time
});

Per-route budgets

Different routes have different needs. Your marketing homepage and your authenticated dashboard have very different performance characteristics. Set per-route budgets that reflect the actual work each page does.

typescript

PagePulse.setBudget({
  routes: {
    '/':            { lcp: 2500, inp: 200, cls: 0.1 },
    '/dashboard':   { lcp: 3500, inp: 300, cls: 0.1 },
    '/blog/[slug]': { lcp: 2000, inp: 200, cls: 0.05 },
  },
  jsSizeKB: 180,
});

Alerting on breach

Configure alert destinations from the dashboard, or programmatically via the API. PagePulse will fire an alert within 5 minutes of a budget breach.

typescript

PagePulse.configureAlerts({
  destinations: ['slack', 'webhook', 'linear'],
  slack: { channel: '#perf-alerts' },
  webhook: { url: 'https://api.example.com/pagepulse' },
  linear: { teamId: 'eng', label: 'performance' },
});

CI enforcement

Use the @pagepulse/ci package to fail a pull request when a budget would be breached. PagePulse posts a comment to the PR showing exactly which budget was exceeded, by how much, and which module caused the regression.

bash

# In your CI pipeline
npx @pagepulse/ci check \
  --project site_123 \
  --base origin/main \
  --head HEAD

Budgets evaluated in CI use synthetic measurements from the PR branch against the base branch. They are not a replacement for real-user monitoring; they are a first line of defense.

Have a question about this doc?

Contact support|API reference|support@pagepulse.dev