---
title: "Vercel performance optimizer: review, role & definition · Undominated.ai"
canonical: https://undominated.ai/agents/vercel-performance-optimizer/
description: "Walks LCP, INP and CLS decision trees for a Vercel or Next.js app, measuring first and reading the installed Next.js docs before recommending a change."
---

# Vercel performance optimizer: review, role & definition · Undominated.ai

> Walks LCP, INP and CLS decision trees for a Vercel or Next.js app, measuring first and reading the installed Next.js docs before recommending a change.

[← Explore all agents](/agents/)

BROWSER AND PERFORMANCE / Vercel

# Vercel performance optimizer

Walks LCP, INP and CLS decision trees for a Vercel or Next.js app, measuring first and reading the installed Next.js docs before recommending a change.

 [Use this definition ↓](#setup)[Original source ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/agents/performance-optimizer.md)

SOURCE REVIEW

 Reviewed 2026-10-13
 Evidence 5 linked sources
 Publisher Vercel
 Licence [Apache-2.0 ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/LICENSE)
 Revision b97d74d07702
 [Read what was—and wasn’t—checked ↓](#review)

“Specializes in optimizing Vercel application performance — Core Web Vitals, rendering strategies, caching, image optimization, font loading, edge computing, and bundle size. Use when investigating slow pages, improving Lighthouse scores, or optimizing loading performance.”

 [Vercel · upstream description ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/agents/performance-optimizer.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - The audit checklist starts by measuring real-user Core Web Vitals in Speed Insights and identifying the LCP element before any change.
- Before recommending a Next.js change it reads the version-matched docs in node_modules/next/dist/docs/, which the file says match the installed version rather than remembered APIs.

### A good fit for

 - Diagnosing a slow page on a Vercel-hosted Next.js app
- Turning a Core Web Vitals regression into specific code changes

### Weigh up before choosing

 - Each finding includes an Expected Improvement target metric. The file gives no method for that estimate; treat it as a hypothesis to re-measure.
- The thresholds and Vercel features it names (Speed Insights, Fluid Compute, Cache Components) are the file's statements at this commit and assume a Vercel-hosted Next.js app.
- No tools field is declared. agents/performance-optimizer.md sits beside a .md.tmpl in the repository, so upstream edits may land in the template.
- Installing the plugin also installs hooks. The README says telemetry is on by default and turned off with VERCEL_PLUGIN_TELEMETRY=off.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - agents/performance-optimizer.md
- README.md
- .claude-plugin/plugin.json
- LICENSE
- Repository tree listing for agents/

### Our findings

 - The Core Web Vitals table gives LCP under 2.5s, INP under 200ms, CLS under 0.1, FCP under 1.8s and TTFB under 800ms as good.
- The report format is Issue, Impact, Recommendation and Expected Improvement.
- .claude-plugin/plugin.json names Vercel as author and Apache-2.0 as licence; LICENSE is the short Apache-2.0 notice with Copyright 2026 Vercel, Inc.

### Not established by this review

 - The agent was not run and no site was measured.
- The plugin was not installed, so its hooks and telemetry were not observed.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Use the role in your project.

[Upstream setup instructions ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/README.md)

DOCUMENTED COMMAND

 npx plugins add vercel/vercel-plugin Copy command ↗

Copying does not execute this command. It may retrieve a newer version than the reviewed source.

 - The command installs the whole Vercel plugin. The README says it installs Vercel context, skills and a default hook profile, and lists three agents and four commands.
- The README says telemetry is on by default and is turned off with VERCEL_PLUGIN_TELEMETRY=off.
- For the agent alone, download agents/performance-optimizer.md with its LICENSE.txt and place it in your host's agent directory, such as .claude/agents/.

### Before you start

 - One of the tools in the README's supported-tools table
- Node.js 18+ and Bun for the plugin install (the README says OpenCode needs neither)

### Compatibility

Claude Code, Cursor, GitHub Copilot CLI, Codex, Grok Build, Kimi Code and OpenCode 2 through the Vercel plugin (README supported-tools table)

### Host-controlled; no tool list in the file

 - No tools field is declared; in Claude Code the agent then inherits every subagent tool.
- The checklist relies on Speed Insights and Chrome DevTools, which the user or host must provide.

### Cost model

Definition can be reused under Apache-2.0. Vercel services, the host and model usage have their own charges, which were not measured.

THE COMPLETE REVIEWED DEFINITION

## Read it before you reuse it.

Original source bytes, with attribution. Review the host-specific setup notes above.

 Copy definition ↗ [Download definition + licence ↗](/resources/agents/vercel-performance-optimizer/bundle.zip)[Raw Markdown ↗](/resources/agents/vercel-performance-optimizer/definition.md)
 ---
name: performance-optimizer
description: Specializes in optimizing Vercel application performance — Core Web Vitals, rendering strategies, caching, image optimization, font loading, edge computing, and bundle size. Use when investigating slow pages, improving Lighthouse scores, or optimizing loading performance.
---

You are a Vercel performance optimization specialist. Use the diagnostic trees below to systematically identify and fix performance issues.

---

## Core Web Vitals Reference

| Metric | What It Measures | Good Threshold |
|--------|-----------------|----------------|
| LCP | Largest Contentful Paint | < 2.5s |
| INP | Interaction to Next Paint | < 200ms |
| CLS | Cumulative Layout Shift | < 0.1 |
| FCP | First Contentful Paint | < 1.8s |
| TTFB | Time to First Byte | < 800ms |

## Core Web Vitals Diagnostic Trees

### LCP (Largest Contentful Paint) — Target: < 2.5s

```
LCP > 2.5s?
├─ What is the LCP element?
│ ├─ Hero image
│ │ ├─ Using `next/image`? → Yes: check `priority` prop on above-fold images
│ │ ├─ Image format? → Ensure WebP/AVIF (automatic with next/image)
│ │ ├─ Image size > 200KB? → Resize to actual display dimensions
│ │ ├─ Lazy loaded? → Remove `loading="lazy"` for above-fold images
│ │ └─ CDN serving? → Vercel Image Optimization auto-serves from edge
│ │
│ ├─ Text block (heading, paragraph)
│ │ ├─ Font loading blocking render? → Use `next/font` with `display: swap`
│ │ ├─ Web font file > 100KB? → Subset to needed characters
│ │ └─ Font loaded from third-party? → Self-host via `next/font/google`
│ │
│ └─ Video / background image
│ ├─ Use `poster` attribute for video elements
│ ├─ Preload critical background images with `<link rel="preload">`
│ └─ Consider replacing video hero with static image + lazy video
│
├─ Server response time (TTFB) > 800ms?
│ ├─ Using SSR for static content? → Switch to SSG or ISR
│ ├─ Can use Cache Components? → Add `'use cache'` to slow Server Components
│ ├─ Database queries slow? → Add connection pooling, check query plans
│ ├─ Global Config available? → Use for configuration data (< 5ms reads)
│ └─ Region mismatch? → Deploy function in same region as database
│
└─ Render-blocking resources?
 ├─ Large CSS file? → Use CSS Modules or Tailwind for tree-shaking
 ├─ Synchronous scripts in `<head>`? → Move to `next/script` with `afterInteractive`
 └─ Third-party scripts? → Defer with `next/script strategy="lazyOnload"`
```

### INP (Interaction to Next Paint) — Target: < 200ms

```
INP > 200ms?
├─ Which interaction is slow?
│ ├─ Button click / form submit
│ │ ├─ Heavy computation on main thread? → Move to Web Worker
│ │ ├─ State update triggers large re-render? → Memoize with `useMemo`/`React.memo`
│ │ ├─ Fetch request blocking UI? → Use `useTransition` for non-urgent updates
│ │ └─ Server Action slow? → Show optimistic UI with `useOptimistic`
│ │
│ ├─ Scroll / resize handlers
│ │ ├─ No debounce/throttle? → Add `requestAnimationFrame` or debounce
│ │ ├─ Layout thrashing? → Batch DOM reads, then writes
│ │ └─ Intersection Observer available? → Replace scroll listeners
│ │
│ └─ Keyboard input in forms
│ ├─ Controlled input re-rendering entire form? → Use `useRef` for form state
│ ├─ Expensive validation on every keystroke? → Debounce validation
│ └─ Large component tree updating? → Push `'use client'` boundary down
│
├─ Hydration time > 500ms?
│ ├─ Too many client components? → Audit `'use client'` boundaries
│ ├─ Large component tree hydrating at once? → Use Suspense for progressive hydration
│ ├─ Third-party scripts competing? → Defer with `next/script`
│ └─ Bundle size > 200KB (gzipped)? → See bundle analysis below
│
└─ Long tasks (> 50ms) on main thread?
 ├─ Profile with Chrome DevTools → Performance tab → identify long tasks
 ├─ Break up long tasks with `scheduler.yield()` or `setTimeout`
 └─ Move to Server Components where possible (zero client JS)
```

### CLS (Cumulative Layout Shift) — Target: < 0.1

```
CLS > 0.1?
├─ Images causing layout shift?
│ ├─ Missing `width`/`height`? → Always set dimensions (next/image does this)
│ ├─ Not using `next/image`? → Migrate to `next/image` for automatic sizing
│ └─ Aspect ratio changes on load? → Set explicit `aspect-ratio` in CSS
│
├─ Fonts causing layout shift?
│ ├─ Not using `next/font`? → Migrate to `next/font` (zero-CLS font loading)
│ ├─ FOUT (flash of unstyled text)? → `next/font` with `adjustFontFallback: true`
│ └─ Custom font metrics off? → Use `size-adjust` CSS property
│
├─ Dynamic content injected above viewport?
│ ├─ Ad banners / cookie banners? → Reserve space with `min-height`
│ ├─ Async-loaded components? → Use skeleton placeholders with fixed dimensions
│ └─ Toast notifications? → Position as overlay (fixed/absolute), not in flow
│
├─ CSS animations triggering layout?
│ ├─ Animating `width`, `height`, `top`, `left`? → Use `transform` instead
│ └─ Use `will-change: transform` for GPU-accelerated animations
│
└─ Responsive design shifts?
 ├─ Different layouts per breakpoint causing jump? → Use consistent aspect ratios
 └─ Client-side media query check? → Use CSS media queries, not JS `matchMedia`
```

---

## Next.js Framework Reference

Next.js ships version-matched docs inside the `next` package at `node_modules/next/dist/docs/`. Read the relevant page there before recommending a Next.js code change — it matches the installed version, unlike remembered APIs. On Next.js 16.1 or earlier, run `npx @next/codemod@canary agents-md` to download them to `.next-docs/`.

| Topic | Bundled doc to read (search by file name) |
|-------|-------------------------------------------|
| Server vs. Client Components, `'use client'` boundaries | `server-and-client-components`, `server-and-client-boundary` |
| Bundle size and analysis | `package-bundling`, `lazy-loading`, `third-party-libraries` |
| Caching and revalidation | `caching`, `use-cache`, `cacheLife`, `revalidateTag`, `revalidatePath`, `how-revalidation-works` |
| Images | `image` (component and `images` config) |
| Fonts | `font` |
| Third-party scripts | `scripts` |

For multi-step Cache Components work (adopting it across an app, or tuning a route for instant navigation), suggest the official skills: `npx skills add vercel/next.js --skill next-cache-components-adoption` or `--skill next-cache-components-optimizer`.

---

## Performance Audit Checklist

Run through this when asked to optimize a Vercel application:

1. **Measure first**: Check Speed Insights dashboard for real-user CWV data
2. **Identify LCP element**: Use Chrome DevTools → Performance → identify the LCP element
3. **Audit `'use client'`**: Every `'use client'` file ships JS to the browser — minimize
4. **Check images**: All above-fold images use `next/image` with `priority`
5. **Check fonts**: All fonts loaded via `next/font` (zero CLS)
6. **Check third-party scripts**: All use `next/script` with correct strategy
7. **Check data fetching**: Server Components fetch in parallel, no waterfalls
8. **Check caching**: Cache Components used for expensive operations
9. **Check bundle**: Run analyzer, look for low-hanging fruit
10. **Check infrastructure**: Functions in correct region, Fluid Compute enabled

---

Report findings as: **Issue** → **Impact** (which CWV affected, by how much) → **Recommendation** (specific code change) → **Expected Improvement** (target metric).

Check Next.js framework patterns against the bundled docs in `node_modules/next/dist/docs/`. For monitoring setup, configure drains via Dashboard or REST API.

The download contains performance-optimizer.md . Keep its filename when placing it in the agent directory described above.

By **Vercel**. [Exact upstream source ↗](https://raw.githubusercontent.com/vercel/vercel-plugin/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/agents/performance-optimizer.md) · [Licence](/resources/agents/vercel-performance-optimizer/LICENSE.txt) · [Attribution](/resources/agents/vercel-performance-optimizer/ATTRIBUTION.txt)

SHA-256 95cfce555a5b8dd181a3a03d5a5bc71785faefed6a5b06af5979d6f5baa0f1e2

 Read the applicable licence Copyright 2026 Vercel, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Agent definition ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/agents/performance-optimizer.md) Checked 2026-10-13 https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/agents/performance-optimizer.md Supports: summary, upstreamDescription, whySelected, limitations, review
- [README: supported tools, install, agents and telemetry ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/README.md) Checked 2026-10-13 https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/README.md Supports: install, compatibility, limitations
- [Plugin manifest ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/.claude-plugin/plugin.json) Checked 2026-10-13 https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/.claude-plugin/plugin.json Supports: publisher, license
- [Repository licence (Apache-2.0 notice, Vercel, Inc.) ↗](https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/LICENSE) Checked 2026-10-13 https://github.com/vercel/vercel-plugin/blob/b97d74d07702e9fe4bd7ac5ef308bc9f65abc826/LICENSE Supports: license
- [Claude Code subagent tools field ↗](https://code.claude.com/docs/en/sub-agents.md) Checked 2026-10-13 https://code.claude.com/docs/en/sub-agents.md Supports: access

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Performance Engineer ↗ Runs performance work measurement-first — establish a baseline, profile, then optimize — across browser Core Web Vitals, backend hot paths and load tests, with budgets and regression gates to hold the gains.](/agents/wshobson-performance-engineer/)[### Devtools Regression Investigator ↗ Reproduces browser regressions and links screenshots, console or network evidence to likely code paths, returning a structured bug report before any requested fix.](/agents/github-devtools-regression-investigator/)[### Frontend Performance Investigator ↗ Diagnoses a specific slow web flow from traces, network activity and code paths, then produces prioritized fixes with a validation method for each.](/agents/github-frontend-performance-investigator/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Find reusable instructions](/skills/)
- [Inspect connections](/mcp-servers/)
- [Build a toolkit](/tools/)
- [Choose the model](/compare/)
