Skip to main content
skill CX Codex

nextjs-bundle-optimizer — Claude Code skill for Next.js builds

nextjs-bundle-optimizer measures Next.js bundle size and build time, then checks optimizations one change at a time. Useful when First Load JS grows or production builds slow down.

MIT 152 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill nextjs-bundle-optimizer -a claude-code
Open on GitHub

What nextjs-bundle-optimizer does

The skill records baseline metrics, finds large modules, and matches them to optimization recipes. After a single change, it rebuilds the app, compares results with the baseline, and runs build, type, and test checks. A passing improvement can be committed; a failure or lack of gains calls for a revert.

For Next.js 16, it uses next experimental-analyze; Turbopack handles some optimizations automatically. Projects on Next.js 15 or earlier using webpack get @next/bundle-analyzer instead. The workflow needs git, jq on PATH, and a clean working tree, so uncommitted changes block its checkpoint checks. Start setup from the app root with bash scripts/baseline.sh --setup.

What it helps with

  • find modules inflating First Load JS
  • trace slow production builds to their bottlenecks
  • compare bundle snapshots before and after a change
  • check an optimization with builds, types, and tests
  • revert a change that fails verification

Example prompts for the agent

  • Find the modules adding the most weight to First Load JS in this Next.js app.
  • Compare production build times before and after my change, then check for regressions.
  • Analyze this next experimental-analyze output and suggest one recipe for the largest module.

How to install nextjs-bundle-optimizer

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill nextjs-bundle-optimizer -a claude-code

2Manually: put the files in place

~/.claude/skills/nextjs-bundle-optimizer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nextjs-bundle-optimizer/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nextjs-bundle-optimizer

How do I install nextjs-bundle-optimizer in Claude Code?

Run npx skills add pproenca/dot-skills --skill nextjs-bundle-optimizer -a claude-code. The skill file is at ~/.claude/skills/nextjs-bundle-optimizer/SKILL.md.

What does nextjs-bundle-optimizer do?

It measures Next.js bundles and build times, guides a single optimization change, then checks the result with a build, type checks, and tests.

What does the skill need before it runs?

It requires git, jq on PATH, and a clean working tree. To configure it, run bash scripts/baseline.sh --setup from the app root.

Source text

SKILL.md · MIT
---
name: nextjs-bundle-optimizer
description: "Next.js 16 bundle-size and build-time optimization — runs a data-driven iteration loop: measure baseline → analyze top offenders → apply ONE recipe → re-measure → verify nothing broke (build + types + tests + no regression) → commit or revert. Built for Next.js 16 with Turbopack default, and falls back to webpack-mode tooling when the project hasn't migrated yet. Triggers on phrases like \"First Load JS is huge\", \"bundle size\", \"build takes too long\", \"page is slow to TTI\", \"reduce bundle\", \"tree-shake\", or when the user shares output from `next experimental-analyze` / `@next/bundle-analyzer` — even if the user doesn't say \"optimize\" explicitly."
---
# Next.js Bundle & Build-Time Optimizer

Data-driven optimization loop for Next.js 16 applications. The skill orchestrates `next experimental-analyze`, builds, type checks, and tests to make verifiable improvements one change at a time.

## When to Apply

Use this skill when:
- The user wants to reduce bundle size / First Load JS / route bundles in a Next.js 16 app.
- Production builds are slow and the user wants to diagnose and fix the bottleneck.
- The user shares analyzer output, a screenshot of the treemap, or asks "why is `<X>` so big?"
- A new dependency was added and bundles grew — they want to understand why and unwind it.
- The user wants to set a performance budget and enforce it iteratively.

## Why iterative (not "apply all optimizations at once")

Bundle optimization is full of foot-guns. Examples:
- Moving a "client-only" dep behind `next/dynamic` can break SSR consumers that depended on its presence at first paint.
- `experimental.optimizePackageImports` with the wrong package can mis-resolve subpath exports.
- Aggressive `modularizeImports` regex rewrites can hit unintended modules.
- Narrowing the polyfill target can break older mobile browsers in production.

The only reliable way is: **one change, measure, verify, commit (or revert)**. This skill enforces that discipline through scripts.

## Prerequisites

- Next.js 16+ project (the skill auto-detects from `package.json`).
- `git` (the workflow uses commits as checkpoints and revert as rollback).
- `jq` available on PATH (used by analyze/compare scripts).
- A clean working tree before starting (the verify step uses `git status` to confirm).
- For projects still on Next.js 15 or earlier in webpack mode: the skill detects this and uses `@next/bundle-analyzer` instead of `experimental-analyze`. See [gotchas.md](gotchas.md).

## Setup

On first use, run:

```bash
bash scripts/baseline.sh --setup
```

This walks through `config.json` interactively. If `config.json` already has values, scripts use those and skip the prompts.

## Workflow Overview

```
┌── 1. baseline ──┐   Clean build, snapshot bundles + timing → baselines/{timestamp}/
│                 │
│   2. analyze ───┤   Run `next experimental-analyze --output`, extract top offenders
│                 │
│   3. diagnose ──┤   Map each offender to a recipe in references/optimizations.md
│                 │
│   ── apply ─────┤   User (or agent) applies ONE recipe. Skill helps draft the change.
│                 │
│   4. measure ───┤   Re-build, re-analyze, save to iterations/{n}/
│                 │
│   5. compare ───┤   Diff vs baseline; flag regressions; print delta table
│                 │
│   6. verify ────┤   Build + tsc + tests + no overall regression. Hard PASS/FAIL.
│                 │
│   commit OR ────┘   `git commit` (PASS+improvement) or `git revert` (FAIL/no win)
│   revert
│
└── loop back to step 2 with new baseline if you want a fresh measurement point.
```

Read [references/workflow.md](references/workflow.md) for the detailed loop with error handling, rollback procedures, and what each script's output looks like.

## Quick Reference

### Scripts (run from the Next.js app root)

| Script | Purpose | Output |
|--------|---------|--------|
| `scripts/baseline.sh` | Establish the reference point | `baselines/{ts}/{bundle,timing,manifest}.json` |
| `scripts/analyze.sh` | Run analyzer, parse top offenders | `iterations/{n}/findings.json` |
| `scripts/diagnose.sh [findings.json]` | Map findings → recipes | stdout: prioritized recipe list |
| `scripts/measure.sh` | Re-measure after a change | `iterations/{n}/{bundle,timing}.json` |
| `scripts/compare.sh [baseline] [current]` | Diff snapshots | stdout: delta table; exit 1 on regression |
| `scripts/verify.sh` | Full verification | exit 0 = safe to commit, exit 1 = revert |

### Optimization Recipes

[references/optimizations.md](references/optimizations.md) catalogs recipes by analyzer signal:

**Bundle size**
- Barrel-import bloat → `experimental.optimizePackageImports` (webpack) / auto in Turbopack
- Heavy client lib pulled in on every route → `next/dynamic({ ssr: false })`
- Server-only lib imported from a client component → move to Server Component
- Duplicate dependency versions → dedupe via `overrides` / `resolutions`
- Polyfill bloat → tighten `browserslist`
- Per-icon imports for icon libraries

**Build time**
- Enable `experimental.turbopackFileSystemCacheForBuild`
- Narrow `transpilePackages` (overuse balloons compile time)
- Split `tsc --noEmit` from `next build` in CI
- Identify single-file bottlenecks with `NEXT_TURBOPACK_TRACING=1`

Each recipe documents: **signal → fix → expected impact → verify step**.

## Gotchas

See [gotchas.md](gotchas.md) for accumulated failure points. Initially seeded with the most common Next.js 16 traps:
- `next build` no longer prints First Load JS — don't grep build output for it.
- `optimizePackageImports` is a no-op under Turbopack (default in 16) — Turbopack auto-optimizes.
- Comparing build times needs cache state controlled — either delete `.next/` (cold) or pre-warm (warm).

## Related Skills

- `vercel:nextjs` — general Next.js App Router guidance; consult for refactoring decisions while applying recipes.
- `vercel:turbopack` — for build-time debugging beyond what this skill covers.
- `vercel:next-cache-components` — when a recipe touches caching boundaries.

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Frontend and UI →

From the same set139

The whole set →
react-hook-form-audit react-hook-form-audit scans a Next.js App Router project for 16 React Hook Form anti-patterns and writes a markdown report citing file:line. Read-only. CX Codex +1 158installs codex-goals Guidance for writing and checking persistent Codex Goals, from a verifiable finish line to iteration rules. Useful when a task spans turns but has a clear outcome. CX Codex +1 158installs expo-design-system expo-design-system is a Claude Code skill for building and reviewing shared UI in Expo and React Native apps for web and iOS. It applies to tokens, themes, and reusable components. CX Codex +1 156installs complexity-optimizer complexity-optimizer detects algorithmic complexity bottlenecks in codebases and suggests safe runtime optimizations. CX Codex +1 156installs implementation-design-patterns implementation-design-patterns is a Claude Code skill that identifies a Gang of Four pattern from a problem description and explains when to apply or avoid it. CX Codex +1 151installs better-auth A TypeScript skill for Better Auth: instance setup, adapter choice, sessions and cookies, plugins, plus migration from another auth library. CX Codex +1 150installs diataxis diataxis sorts technical docs into four modes: tutorial, how-to, reference, explanation. Tells the agent which one a page needs before it starts writing. CX Codex +1 149installs drizzle-sqlite-scaffold drizzle-sqlite-scaffold generates boilerplate for Drizzle ORM + SQLite: config, client with pragmas, table schemas, CRUD modules and validators. Triggers on phrases like “add a table for X” or “set up the DB”. CX Codex +1 149installs

Project sponsors

Companies that keep this analytics open