Next.js bundle optimizer skill: shrink client bundles with your agent

Source: vercel/next.js · Maintainer: Vercel · License: MIT · Checked: 24 October 2026

What is the next-bundle-optimizer skill?

next-bundle-optimizer is the official Next.js skill for finding and cutting oversized client bundles. It has a coding agent capture Turbopack's bundle analysis, rank what the browser has to load before a route becomes usable, and either report the candidates or fix them one verified change at a time. It works with Claude Code, Codex, Cursor and other agents that read the SKILL.md format.

The skill lives in the skills/ folder of the vercel/next.js repo, next to the other Next.js workflow skills. The Next.js AI coding agents guide describes it this way: it "uses Turbopack's bundle analyzer to identify sources of large client-side bundles that impact your site's initial load performance." The guide's version history lists the skill as added in v16.4.0.

Its description reads: "Audit and reduce Next.js browser initial-load work. Use for slow route startup, oversized client bundles, duplicate browser dependencies, or features that can wait for interaction."

As of 24 October 2026, its skills.sh page listed 1.6K installs (snapshot, 24 October 2026). It is new: skills.sh first saw it on 6 October 2026.

What does it do?

The SKILL.md runs six steps, each ending in a "Done" check:

1. Set the scope. The whole app by default, or a route, dependency or feature you name. Audit mode is the default; fix mode needs an explicit request.
2. Capture and export a baseline. It runs next analyze --output --snapshot <name> to build and save analyzer data without serving the UI, then streams it with next analyze export into a gzipped JSON Lines file.
3. Interpret the evidence. It reads the graph schema from your installed Next.js and streams the export through a script instead of loading it all into context.
4. Explain each candidate. It inspects real source and exact importers, and ranks candidates by size, repetition, runtime cost, whether they are needed before interaction, and risk.
5. Verify one change (fix mode only). One small change, a new after snapshot, the same metric compared, plus tests and a type check.
6. Report and stop. Snapshot names, deltas, importers, check results and blockers.

The capture and export commands it uses look like this (from the skill, with pnpm; use your own package manager):

set -o pipefail
pnpm exec next analyze --output --snapshot 'audit-before-unique-1'
pnpm exec next analyze export --snapshot 'audit-before-unique-1' | gzip > /tmp/analyze-app-before.jsonl.gz

The --output, --snapshot, --route and --dist-dir options match the Next.js CLI reference, which says next analyze "doesn't produce an application build." Run without --output, the same command serves a local analyzer where you can filter bundles by route, switch between client and server views, and follow the import chain that explains why a module is included. The skill uses the saved export instead, so the agent can process the graph with a script and keep before and after files side by side.

For broad audits, the skill adds a graph pass: community detection (Louvain or Leiden) to find feature clusters, then a directed min-cut to find the smallest set of import changes that would detach a heavy feature from the initial load. Every candidate needs a checklist covering scope, coverage, attribution, reachability, source checks and method before the agent proposes an edit.

What's in the folder:

• SKILL.md: the six-step workflow.
• references/fix-patterns.md: lazy-loading interaction features, removing duplicate browser dependencies, moving display-only work to server rendering, and other assets such as polyfills, barrels, fonts and WASM.
• references/graph-methods.md: how to build the graph, cluster it and run the min-cut.

How do you install it?

The Next.js docs give this command for the skills CLI:

npx skills add vercel/next.js --skill next-bundle-optimizer

skills.sh shows the same install with the full URL, npx skills add https://github.com/vercel/next.js --skill next-bundle-optimizer. Add -g for all projects or -a claude-code to target Claude Code. In Claude Code the folder lands in .claude/skills/next-bundle-optimizer/, or ~/.claude/skills/next-bundle-optimizer/ with -g, per the Claude Code skills docs. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

The skill may ask to install two siblings when they fit the task: next-cache-components-optimizer for static-shell work and next-dev-loop for checking an edit in the running app. You can add them up front:

npx skills add vercel/next.js --skill next-bundle-optimizer --skill next-cache-components-optimizer --skill next-dev-loop

How do you use it?

Start in audit mode, read the report, then ask for fixes on the candidates you agree with.

The Next.js docs suggest this prompt for an audit:

Use the next-bundle-optimizer skill to produce a report of the initial load performance of this site.

More example prompts (suggestions, not quotes from the docs):

• Audit only /dashboard with next-bundle-optimizer. Don't change any files.
• We ship two copies of date-fns to the browser. Find out why and propose a fix.
• Fix mode: lazy-load the chart editor on /reports if the bundle analysis supports it, and keep keyboard focus behavior the same.
• Compare the before and after snapshots for the last change and tell me whether to keep it.

Requirements: a Next.js app on a version with next analyze export (v16.4.0 or later per the CLI reference), its package manager, and the ability to run a build. Interactive exploration can use the analyzer UI that next analyze serves on port 4000 by default.

Tips and limits

• Build evidence, not browser timing. The skill treats the analysis as "build evidence" and says claims about real requests, timing or transfer savings "need separate evidence."
• Codex sandbox. The SKILL.md says that if the sandbox blocks TCP port binding, "as Codex's does," the capture must run outside it.
• Snapshot names matter. Reusing a name replaces the earlier capture, so keep distinct before and after names.
• Changes must earn their place. In fix mode a change stays only if "the scoped metric improves and the intended behavior passes its checks"; otherwise it is reverted.
• It asks before visible changes. The skill asks before changing visible behavior, timing, compatibility or a trust boundary.
• Security audit. On 24 October 2026 its skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass, Snyk: Pass.

The vercel/next.js repo is MIT licensed, so you can copy and adapt the skill if you keep the copyright notice.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and both reference files. Import next-dev-loop and the cache components optimizer the same way if you use them together. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Vercel or the Next.js team.

Similar skills

• Next.js cache components optimizer skill: the sibling skill for making a route's static shell instant.
• next-dev-loop skill: the Next.js skill this one uses to verify edits in a running app.
• React best practices skill: Vercel's rules for bundle size, waterfalls and re-renders, useful while writing code.
• Performance skill: a framework-agnostic, measurement-first performance skill.
• Vercel optimize skill: finds cost and speed issues from a deployed project's Vercel metrics.