Bundle Cop
GitHubGet Started

Docs

Install and configure Bundle Cop to optimize Next.js bundle size on Vercel — budgets, attribution, and deploy reports.

Install the adapter

Requires Next.js 16+. Package: bundle-cop-vercel-plugin.

pnpm add bundle-cop-vercel-plugin

Point Next.js at the adapter in next.config.ts:

import type { NextConfig } from 'next'
import { createRequire } from 'node:module'

const require = createRequire(import.meta.url)

const nextConfig: NextConfig = {
  adapterPath: require.resolve('bundle-cop-vercel-plugin/adapter'),
}

export default nextConfig

After next build, inspect bundle-report.json in the project root.

Budgets config

Optional. Copy bundle-cop.config.example.json to bundle-cop.config.json:

{
  "budgets": [
    { "path": "/*", "maxSize": "250kb", "enforce": "warn" },
    { "path": "/dashboard", "maxSize": "400kb", "enforce": "error" }
  ],
  "ignore": ["node_modules/**/locales/**"],
  "githubComment": true,
  "suggestions": true
}
  • enforce: "warn" — log only
  • enforce: "error" — fail the build when over budget
  • suggestions — suggest lighter alternatives (e.g. date-fns for moment)

Prove it locally

The monorepo example/ app imports moment so you can verify attribution:

pnpm install
pnpm build:plugin
pnpm --filter @bundle-cop/example build
# → example/bundle-report.json (moment → app/page.tsx)

Integration app

This site (bundle-cop.vercel.app) hosts setup, dashboard, and webhooks for the Vercel integration.

RoutePurpose
/Product landing
/docsFull documentation (this page)
/setupDefault budgets / fail-on-over-budget guidance
/dashboardBundle history from private Blob reports
POST /api/webhooks/vercelDeployment webhook → Checks
GET /api/reports/[sha]Fetch a report by commit SHA
/privacyPrivacy Policy
/eulaEnd User License Agreement

Environment variables

VariableRequiredPurpose
BLOB_READ_WRITE_TOKENBlob / installsPrivate Blob for reports + OAuth install tokens
INTEGRATION_CLIENT_IDMarketplace installOAuth client ID from Integrations Console
INTEGRATION_CLIENT_SECRETMarketplace installOAuth client secret
VERCEL_WEBHOOK_SECRETWebhooksVerify Vercel webhook signatures
VERCEL_TOKENOptional fallbackPersonal/team token for Checks when no OAuth install token exists. Create at vercel.com/account/tokens, then set on the Bundle Cop project.
GITHUB_APP_*OptionalGitHub Check Runs

Publishing

npm releases ship from GitHub Releases. Tag vX.Y.Z → CI publishes bundle-cop-vercel-plugin.

  1. Ensure repo secret NPM_TOKEN is set
  2. Create a GitHub Release with tag vX.Y.Z
  3. Actions bumps version and runs npm publish