@shiftescape/astro-bundle-budget

Know your bundle. Before it ships.

Build-time JS/CSS budget enforcement for Astro. Inspect every asset, set per-file and per-page thresholds, and fail CI automatically when you go over.

Install GitHub npm ↗
astro build
▶ astro-bundle-budget Analysing bundle…

Asset Type Size
────────────────────────────────────────────────────────────────────
assets/vendor-CHmL3xRz.js js 18.7 kB
assets/index-BxK92mPq.js js 42.3 kB
assets/hoisted-DqW1Pz9a.js js 3.1 kB
assets/index-EpW3Kz7b.css css 6.4 kB
────────────────────────────────────────────────────────────────────
Total JS js 64.1 kB
Total CSS css 6.4 kB

Budget violations

✗ assets/vendor-CHmL3xRz.js: 18.7 kB exceeds budget of 15 kB (+25% over)

error 1 budget violation. Build failed.

features

Everything you need to enforce a budget.

Zero runtime cost — the entire audit happens at build time.

01
Asset table

Every JS and CSS file printed with its exact size after every astro build.

02
Per-file budgets

Target individual files or groups with minimatch glob patterns. First matching rule wins.

03
Per-page budgets

Measure the total JS or CSS payload each generated HTML page references across all its assets.

04
Compression-aware

Set budgets against gzip or brotli — the wire size that actually matters to your users.

05
Fails CI

Exits with code 1 on violation. Works with any CI pipeline. Disable with failOnExceed: false.

06
JSON report

Write a machine-readable report to diff bundle growth between deploys and track trends over time.

configuration

Minimal config, precise control.

Add the integration with no options for a free asset table. Add rules when you're ready to enforce.

astro.config.mjs 
import { defineConfig } from 'astro/config'
import bundleBudget from '@shiftescape/astro-bundle-budget'

export default defineConfig({
  integrations: [
    bundleBudget({
      // per-file rules — first matching glob wins
      budgets: [
        { path: 'assets/vendor-*.js', budget: '50 kB' },
        { path: '**/*.js',            budget: '100 kB' },
        { path: '**/*.css',           budget: '20 kB' },
      ],
      // per-page payload limits
      pageBudgets: [
        { type: 'js',    budget: '150 kB' },
        { type: 'total', budget: '200 kB', compression: 'gzip' },
      ],
    }),
  ],
})
Option Type Default Description
budgets BudgetRule[] [] Per-file glob rules. Each rule sets a max size for matching assets.
pageBudgets PageBudget[] [] Per-page payload limits — total JS, CSS, or combined across a single HTML page.
failOnExceed boolean true Exit 1 when a budget is exceeded. Set to false to warn but never fail.
compression 'none' | 'gzip' | 'brotli' 'none' Measure compressed size per rule. Applies to both file and page budgets.
report boolean false Write a JSON report to outDir for CI diffing and build trend tracking.
reportPath string 'bundle-budget-report.json' Filename for the JSON report, relative to outDir.
verbose boolean false Show every asset and per-page breakdown in the build output.

install

Zero config to get started.

Add the integration — an asset table appears in every build output immediately.

npm npm install -D @shiftescape/astro-bundle-budget
pnpm pnpm add -D @shiftescape/astro-bundle-budget
yarn yarn add -D @shiftescape/astro-bundle-budget
zero-config usage 
import bundleBudget from '@shiftescape/astro-bundle-budget'

export default defineConfig({
  integrations: [bundleBudget()]  // asset table in every build
})