Resources

scripts/ validate-performance-audit.sh references/ performance-patterns.md

Performance Audit

This skill guides you through performing comprehensive performance audits on web applications to identify bottlenecks, optimization opportunities, and performance regressions. Use this when preparing for production deployments, investigating performance issues, or conducting periodic performance reviews.

When to Use This Skill

Conducting pre-deployment performance reviews
Investigating slow page loads or poor user experience
Performing periodic performance audits on existing applications
Validating performance after major feature additions
Preparing for traffic scaling or load testing
Optimizing Core Web Vitals for SEO and user experience

Audit Methodology

A systematic performance audit follows these phases:

Phase 1: Reconnaissance

Objective: Understand the application architecture, tech stack, and performance surface area.

Use discover to map performance-critical code:

discover: queries: - id: bundle_imports type: grep pattern: "^import.from ['"].['"]$" glob: "src//*.{ts,tsx,js,jsx}" - id: database_queries type: grep pattern: "(prisma\.|db\.|query\(|findMany|findUnique|create\(|update\()" glob: "/.{ts,tsx,js,jsx}" - id: component_files type: glob patterns: ["src/components/**/.{tsx,jsx}", "src/app//*.{tsx,jsx}"] - id: api_routes type: glob patterns: ["src/app/api//.{ts,tsx}", "pages/api/**/.{ts,tsx}"] verbosity: files_only

Identify critical components:

Page entry points and route handlers
Heavy npm dependencies (moment.js, lodash, etc.)
Database access patterns and ORM usage
Image and media assets
API endpoints and data fetching logic
Client-side rendering vs server components

Phase 2: Bundle Analysis

Objective: Identify large dependencies, code splitting opportunities, and dead code.

Check Bundle Size

Run bundle analyzer:

precision_exec: commands: - cmd: "npm run build" timeout_ms: 120000 - cmd: "npx @next/bundle-analyzer" timeout_ms: 60000 verbosity: standard

Common issues:

Large dependencies imported on every page (moment.js, lodash, chart libraries)
Multiple versions of the same package (check with npm ls <package> )
Unused dependencies still bundled (tree-shaking failures)
SVG icons imported as components instead of sprite sheets
Entire UI libraries imported instead of individual components

Find Heavy Imports

Search for common performance-heavy packages:

precision_grep: queries: - id: heavy_deps pattern: "import.from '"['"]" glob: "**/.{ts,tsx,js,jsx}" - id: full_library_imports pattern: "import .* from '"['"]$" glob: "**/*.{ts,tsx,js,jsx}" output: format: locations

Optimization strategies:

Bad - importing entire library:

import _ from 'lodash'; // 71KB gzipped import * as Icons from 'react-icons/fa'; // 500+ icons

Good - importing specific modules:

import debounce from 'lodash/debounce'; // 2KB gzipped import { FaUser, FaCog } from 'react-icons/fa'; // Only what you need

Better - using modern alternatives:

// Instead of moment.js (72KB), use date-fns (13KB) or native Intl import { format } from 'date-fns';

// Or native APIs const formatted = new Intl.DateTimeFormat('en-US').format(date);

Check for Code Splitting

Find dynamic imports:

precision_grep: queries: - id: dynamic_imports pattern: "(import\(|React\.lazy|next/dynamic)" glob: "/.{ts,tsx,js,jsx}" - id: large_components pattern: "export (default )?(function|const).\{[\s\S]{2000,}" glob: "src/components//*.{tsx,jsx}" multiline: true output: format: files_only

Code splitting patterns:

Next.js dynamic imports:

import dynamic from 'next/dynamic';

// Client-only components (no SSR) const ChartComponent = dynamic(() => import('./Chart'), { ssr: false, loading: () => <Spinner />, });

// Route-based code splitting const AdminPanel = dynamic(() => import('./AdminPanel'));

React.lazy for client components:

import { lazy, Suspense } from 'react';

const HeavyModal = lazy(() => import('./HeavyModal'));

function App() { return ( <Suspense fallback={<Spinner />}> <HeavyModal /> </Suspense> ); }

Phase 3: Database Performance

Objective: Eliminate N+1 queries, add missing indexes, and optimize query patterns.

Detect N+1 Query Patterns

Search for sequential queries in loops:

precision_grep: queries: - id: potential_n_plus_one pattern: "(map|forEach).await.(findUnique|findFirst|findMany)" glob: "/*.{ts,tsx,js,jsx}" - id: missing_includes pattern: "findMany$\{[^}]where[^}]\}$" glob: "/*.{ts,tsx,js,jsx}" output: format: context context_before: 3 context_after: 3

Common N+1 patterns:

Bad - N+1 query:

const posts = await db.post.findMany();

// Runs 1 query per post! const postsWithAuthors = await Promise.all( posts.map(async (post) => ({ ...post, author: await db.user.findUnique({ where: { id: post.authorId } }), })) );

Good - eager loading with include:

const posts = await db.post.findMany({ include: { author: true, comments: { include: { user: true, }, }, }, });

Better - explicit select for only needed fields:

const posts = await db.post.findMany({ select: { id: true, title: true, author: { select: { id: true, name: true, avatar: true, }, }, }, });

Check for Missing Indexes

Review Prisma schema for index coverage:

precision_read: files: - path: "prisma/schema.prisma" extract: content verbosity: standard

Then search for WHERE clauses:

precision_grep: queries: - id: where_clauses pattern: "where:\s*\{\s*(\w+):" glob: "**/*.{ts,tsx,js,jsx}" output: format: locations

Index optimization:

Add indexes for frequently queried fields:

model Post { id String @id @default(cuid()) title String published Boolean @default(false) authorId String createdAt DateTime @default(now())

// Single column indexes @@index([authorId]) @@index([createdAt])

// Composite index for common query pattern @@index([published, createdAt(sort: Desc)]) }

When to add indexes:

Foreign keys used in WHERE clauses or joins
Fields used in ORDER BY clauses
Fields used in WHERE with pagination (cursor-based)
Composite indexes for multi-field queries

When NOT to add indexes:

Low-cardinality boolean fields (unless part of composite index)
Fields that change frequently (writes become slower)
Tables with very few rows

Optimize Connection Pooling

Check database connection configuration:

precision_grep: queries: - id: prisma_config pattern: "PrismaClient\(.\{[\s\S]?\}" glob: "**/.{ts,tsx,js,jsx}" multiline: true - id: connection_string pattern: "connection_limit=|pool_timeout=|connect_timeout=" glob: ".env" output: format: context context_before: 3 context_after: 3

Optimal connection pool settings:

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient({ datasources: { db: { url: process.env.DATABASE_URL, }, }, log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'], });

export { prisma };

DATABASE_URL with connection pooling:

For serverless (Vercel, AWS Lambda) - use connection pooler

DATABASE_URL="postgresql://user:pass@host:5432/db?connection_limit=10&pool_timeout=10"

For long-running servers - higher limits

DATABASE_URL="postgresql://user:pass@host:5432/db?connection_limit=20&pool_timeout=30"

Phase 4: Rendering Performance

Objective: Eliminate unnecessary re-renders and optimize component rendering.

Detect Unnecessary Re-renders

Find missing memoization:

Note: These patterns are approximations for single-line detection. Multi-line component definitions may require manual inspection.

precision_grep: queries: - id: missing_memo pattern: "(const \w+ = \{|const \w+ = \[|const \w+ = $.$ =>)(?!.useMemo)" glob: "src/components/**/.{tsx,jsx}" - id: missing_callback pattern: "(onChange|onClick|onSubmit)=\{.=>(?!.useCallback)" glob: "src/components/**/.{tsx,jsx}" - id: memo_usage pattern: "(useMemo|useCallback|React\.memo)" glob: "**/*.{tsx,jsx}" output: format: files_only

Memoization patterns:

Bad - recreates object on every render:

function UserProfile({ userId }: Props) { const user = useUser(userId);

// New object reference on every render! const config = { showEmail: true, showPhone: false, };

return <UserCard user={user} config={config} />; }

Good - memoize stable objects:

function UserProfile({ userId }: Props) { const user = useUser(userId);

const config = useMemo( () => ({ showEmail: true, showPhone: false, }), [] // Empty deps - never changes );

return <UserCard user={user} config={config} />; }

Memoize callbacks:

function SearchBar({ onSearch }: Props) { const [query, setQuery] = useState('');

// Memoize callback to prevent child re-renders const handleSubmit = useCallback(() => { onSearch(query); }, [query, onSearch]);

return ( <form onSubmit={handleSubmit}> <input value={query} onChange={(e) => setQuery(e.target.value)} /> </form> ); }

Memoize expensive components:

Check for Virtual List Usage

Find large lists without virtualization:

precision_grep: queries: - id: large_maps pattern: "\{.\.map\(.=>\s*<(?!Virtualized)(?!VirtualList)" glob: "src/**/*.{tsx,jsx}" - id: virtualization pattern: "(react-window|react-virtualized|@tanstack/react-virtual)" glob: "package.json" output: format: locations

Virtual list implementation:

import { useVirtualizer } from '@tanstack/react-virtual';

function VirtualList({ items }: { items: Item[] }) { const parentRef = useRef<HTMLDivElement>(null);

const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 50, // Estimated row height overscan: 5, // Render 5 extra rows for smooth scrolling });

return ( <div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}> <div style={{ height: ${virtualizer.getTotalSize()}px, position: 'relative', }} > {virtualizer.getVirtualItems().map((virtualRow) => ( <div key={virtualRow.index} style={{ position: 'absolute', top: 0, left: 0, width: '100%', transform: translateY(${virtualRow.start}px), }} > <ItemRow item={items[virtualRow.index]} /> </div> ))} </div> </div> ); }

Phase 5: Network Optimization

Objective: Reduce request waterfalls, enable caching, and optimize asset delivery.

Detect Request Waterfalls

Find sequential data fetching:

precision_grep: queries: - id: sequential_fetches pattern: "await fetch.*\n.await fetch" glob: "**/.{ts,tsx,js,jsx}" multiline: true - id: use_effect_fetches pattern: "useEffect\(.fetch" glob: "**/.{tsx,jsx}" output: format: context context_before: 3 context_after: 3

Waterfall optimization:

Bad - sequential requests:

async function loadDashboard() { const userRes = await fetch('/api/user'); if (!userRes.ok) throw new Error(Failed to fetch user: ${userRes.status}); const user = await userRes.json();

const postsRes = await fetch(/api/posts?userId=${user.id}); if (!postsRes.ok) throw new Error(Failed to fetch posts: ${postsRes.status}); const posts = await postsRes.json();

const commentsRes = await fetch(/api/comments?userId=${user.id}); if (!commentsRes.ok) throw new Error(Failed to fetch comments: ${commentsRes.status}); const comments = await commentsRes.json();

return { user, posts, comments }; }

Good - parallel requests:

async function loadDashboard(userId: string) { const [user, posts, comments] = await Promise.all([ fetch(/api/user/${userId}).then(async r => { if (!r.ok) throw new Error(Failed to fetch user: ${r.status}); return r.json(); }), fetch(/api/posts?userId=${userId}).then(async r => { if (!r.ok) throw new Error(Failed to fetch posts: ${r.status}); return r.json(); }), fetch(/api/comments?userId=${userId}).then(async r => { if (!r.ok) throw new Error(Failed to fetch comments: ${r.status}); return r.json(); }), ]);

return { user, posts, comments }; }

Best - server-side data aggregation:

// Single API endpoint that aggregates data server-side async function loadDashboard(userId: string) { const response = await fetch(/api/dashboard?userId=${userId}); if (!response.ok) { throw new Error(Failed to fetch dashboard: ${response.status}); } const data = await response.json(); return data; }

Check Caching Headers

Review cache configuration:

precision_grep: queries: - id: cache_headers pattern: "(Cache-Control|ETag|max-age|stale-while-revalidate)" glob: "/*.{ts,tsx,js,jsx}" - id: next_revalidate pattern: "(revalidate|force-cache|no-store)" glob: "src/app//*.{ts,tsx}" output: format: locations

Next.js caching strategies:

Static data (updates rarely):

// app/products/page.tsx export const revalidate = 3600; // Revalidate every hour

export default async function ProductsPage() { const products = await db.product.findMany(); return <ProductList products={products} />; }

Dynamic data (real-time):

// app/api/posts/route.ts export async function GET() { const posts = await db.post.findMany();

return Response.json(posts, { headers: { 'Cache-Control': 'private, max-age=60, stale-while-revalidate=300', }, }); }

Opt out of caching:

// app/api/user/route.ts export const dynamic = 'force-dynamic';

export async function GET() { const user = await getCurrentUser(); return Response.json(user); }

Optimize Image Loading

Check for image optimization:

precision_grep: queries: - id: img_tags pattern: "<img\s+" glob: "/*.{tsx,jsx,html}" - id: next_image pattern: "(next/image|Image\s+from)" glob: "/*.{tsx,jsx}" output: format: files_only

Image optimization patterns:

Bad - unoptimized images:

Good - Next.js Image component:

import Image from 'next/image';

Responsive images:

Phase 6: Memory Management

Objective: Detect memory leaks and optimize garbage collection.

Find Memory Leak Patterns

Search for cleanup issues:

precision_grep: queries: - id: missing_cleanup pattern: "useEffect\(.*\{[^}]*addEventListener(?!.*return.removeEventListener)" glob: "**/.{tsx,jsx}" multiline: true - id: interval_leaks pattern: "(setInterval|setTimeout)(?!.clear)" glob: "**/.{tsx,jsx}" - id: subscription_leaks pattern: "subscribe\((?!.unsubscribe)" glob: "**/.{ts,tsx,js,jsx}" output: format: context context_before: 3 context_after: 3

Memory leak patterns:

Bad - event listener leak:

useEffect(() => { window.addEventListener('resize', handleResize); // Missing cleanup! }, []);

Good - proper cleanup:

useEffect(() => { window.addEventListener('resize', handleResize);

return () => { window.removeEventListener('resize', handleResize); }; }, []);

Bad - interval leak:

useEffect(() => { const interval = setInterval(() => { fetchUpdates(); }, 5000); // Missing cleanup! }, []);

Good - clear interval:

useEffect(() => { const interval = setInterval(() => { fetchUpdates(); }, 5000);

return () => { clearInterval(interval); }; }, []);

Bad - fetch without abort:

useEffect(() => { fetch('/api/data') .then(r => r.json() as Promise<DataType>) .then(setData) .catch(console.error); // Missing abort on unmount! }, []);

Good - AbortController cleanup:

useEffect(() => { const controller = new AbortController();

fetch('/api/data', { signal: controller.signal }) .then(r => r.json() as Promise<DataType>) .then(setData) .catch(err => { if (err.name !== 'AbortError') console.error(err); });

return () => controller.abort(); }, []);

WeakRef pattern for caches:

class ImageCache { private cache = new Map<string, WeakRef<HTMLImageElement>>();

get(url: string): HTMLImageElement | undefined { const ref = this.cache.get(url); return ref?.deref(); }

set(url: string, img: HTMLImageElement): void { this.cache.set(url, new WeakRef(img)); } }

Phase 7: Server-Side Performance

Objective: Optimize SSR, streaming, and edge function performance.

Check for Blocking Server Components

Find slow server components:

precision_grep: queries: - id: server_components pattern: "export default async function.Page" glob: "src/app//page.{tsx,jsx}" - id: blocking_awaits pattern: "const.await.\n.*const.*await" glob: "src/app//.{tsx,jsx}" multiline: true output: format: locations

Streaming with Suspense:

Bad - blocking entire page:

// app/dashboard/page.tsx export default async function DashboardPage() { const user = await getUser(); const posts = await getPosts(); // Blocks entire page! const analytics = await getAnalytics(); // Blocks entire page!

return ( <div> <UserProfile user={user} /> <PostList posts={posts} /> <Analytics data={analytics} /> </div> ); }

Good - streaming with Suspense:

// app/dashboard/page.tsx import { Suspense } from 'react';

export default async function DashboardPage() { // Only block on critical data const user = await getUser();

return ( <div> <UserProfile user={user} />

  &#x3C;Suspense fallback={&#x3C;PostListSkeleton />}>
    &#x3C;PostList />
  &#x3C;/Suspense>
  
  &#x3C;Suspense fallback={&#x3C;AnalyticsSkeleton />}>
    &#x3C;Analytics />
  &#x3C;/Suspense>
&#x3C;/div>

); }

// Separate component for async data async function PostList() { const posts = await getPosts(); return <div>{/* render posts */}</div>; }

Optimize Edge Functions

Check edge runtime usage:

precision_grep: queries: - id: edge_config pattern: "export const runtime = '"['"]" glob: "/*.{ts,tsx}" - id: edge_incompatible pattern: "(fs\.|path\.|process\.cwd)" glob: "/api/**/*.{ts,tsx}" output: format: locations

Edge runtime best practices:

// app/api/geo/route.ts export const runtime = 'edge';

export async function GET(request: Request) { // Access edge-specific APIs const geo = request.headers.get('x-vercel-ip-country');

return Response.json({ country: geo, timestamp: Date.now(), }); }

Phase 8: Core Web Vitals

Objective: Measure and optimize LCP, INP, and CLS.

Measure Web Vitals

Add Web Vitals reporting:

// app/layout.tsx or app/web-vitals.tsx 'use client';

import { useEffect } from 'react'; import { onCLS, onFCP, onINP, onLCP, onTTFB } from 'web-vitals';

import type { Metric } from 'web-vitals';

function sendToAnalytics(metric: Metric) { const body = JSON.stringify(metric); const url = '/api/analytics';

if (navigator.sendBeacon) { navigator.sendBeacon(url, body); } else { fetch(url, { body, method: 'POST', keepalive: true }); } }

export function WebVitals() { useEffect(() => { onCLS(sendToAnalytics); onFCP(sendToAnalytics); onINP(sendToAnalytics); onLCP(sendToAnalytics); onTTFB(sendToAnalytics); }, []);

return null; }

Optimize LCP (Largest Contentful Paint)

Target: < 2.5s

Common LCP issues:

Large hero images not optimized
Web fonts blocking render
Server-side rendering too slow
No resource prioritization

Optimization:

// Priority image loading <Image src="/hero.jpg" alt="Hero" width={1200} height={630} priority // Preload this image! />

// Font optimization <link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossOrigin="anonymous" />

Optimize INP (Interaction to Next Paint)

Target: < 200ms

Common INP issues:

Heavy JavaScript blocking main thread
Expensive event handlers
Layout thrashing

Optimization:

// Debounce expensive handlers import { useDebouncedCallback } from 'use-debounce';

function SearchInput() { const debouncedSearch = useDebouncedCallback( (value: string) => { performSearch(value); }, 300 // Wait 300ms after user stops typing );

return ( <input onChange={(e) => debouncedSearch(e.target.value)} placeholder="Search..." /> ); }

Optimize CLS (Cumulative Layout Shift)

Target: < 0.1

Common CLS issues:

Images without dimensions
Ads or embeds without reserved space
Web fonts causing FOIT/FOUT
Dynamic content injection

Optimization:

// Always specify image dimensions <Image src="/photo.jpg" alt="Photo" width={800} height={600} />

// Reserve space for dynamic content <div style={{ minHeight: '200px' }}> <Suspense fallback={<Skeleton height={200} />}> <DynamicContent /> </Suspense> </div>

// Use font-display for web fonts @font-face { font-family: 'Inter'; src: url('/fonts/inter.woff2') format('woff2'); font-display: swap; // Prevent invisible text }

Audit Reporting

Structure findings with impact, effort, and priority:

Report Template

Performance Audit Report

Executive Summary

Date: 2026-02-16
Auditor: Engineer Agent
Scope: Full application performance review
Overall Score: 6.5/10

Critical Issues (Fix Immediately)

1. N+1 Query in Post Listing

File: src/app/posts/page.tsx
Issue: Sequential database queries for each post author
Impact: Page load time 3.2s -> should be <500ms
Effort: 15 minutes
Fix: Add include: { author: true } to findMany query

High Priority (Fix This Week)

2. Missing Bundle Splitting

Files: src/app/admin/*
Issue: Admin panel code (250KB) loaded on all pages
Impact: Initial bundle size 850KB -> should be <200KB
Effort: 1 hour
Fix: Use next/dynamic for admin routes

Medium Priority (Fix This Month)

3. Unoptimized Images

Files: Multiple components using <img> tags
Issue: LCP of 4.1s due to large unoptimized images
Impact: Poor Core Web Vitals, SEO penalty
Effort: 2 hours
Fix: Migrate to next/image with proper sizing

Low Priority (Backlog)

4. Missing Memoization

Files: src/components/Dashboard/*.tsx
Issue: Unnecessary re-renders on state changes
Impact: Minor UI lag on interactions
Effort: 3 hours
Fix: Add useMemo, useCallback, React.memo

Performance Metrics

Metric	Current	Target	Status
LCP	4.1s	<2.5s	FAIL
INP	180ms	<200ms	PASS
CLS	0.05	<0.1	PASS
Bundle Size	850KB	<200KB	FAIL
API Response	320ms	<500ms	PASS

Validation Script

Use the validation script to verify audit completeness:

bash scripts/validate-performance-audit.sh

The script checks for:

Bundle analysis artifacts
Database query patterns
Memoization usage
Image optimization
Caching headers

References

See references/performance-patterns.md for detailed anti-patterns and optimization techniques.

performance-audit

Safety Notice

Copy this and send it to your AI assistant to learn

For serverless (Vercel, AWS Lambda) - use connection pooler

For long-running servers - higher limits

Performance Audit Report

Executive Summary

Critical Issues (Fix Immediately)

1. N+1 Query in Post Listing

High Priority (Fix This Week)

2. Missing Bundle Splitting

Medium Priority (Fix This Month)

3. Unoptimized Images

Low Priority (Backlog)

4. Missing Memoization

Performance Metrics

Source Transparency

Related Skills

security-audit

accessibility-audit

error-recovery