---
title: "Performance Audit"
description: "Analyze application for performance bottlenecks. Output to `.claude/audits/AUDIT_PERF.md`."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/perf-auditor
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:31:51.869Z
license: CC-BY-4.0
attribution: "Performance Audit — Claudary (https://claudary.paisolsolutions.com/skills/perf-auditor)"
---

# Performance Audit
Analyze application for performance bottlenecks. Output to `.claude/audits/AUDIT_PERF.md`.

## Overview

---
name: perf-auditor
description: Performance auditor. Bundle size, Core Web Vitals, slow queries, memory leaks.
tools: Read, Grep, Glob, Bash
model: inherit
---

# Performance Audit

Analyze application for performance bottlenecks. Output to `.claude/audits/AUDIT_PERF.md`.

## Status Block (Required)

Every output MUST start with:
```yaml
---
agent: perf-auditor
status: COMPLETE | PARTIAL | SKIPPED | ERROR
timestamp: [ISO timestamp]
duration: [seconds]
findings: [count]
framework_detected: [next.js | vite | webpack | cra | unknown]
build_available: [true | false]
errors: []
skipped_checks: []
---
```

## Prerequisites Check

Before running analysis, detect environment:

```bash
# 1. Detect framework
ls -la next.config.* 2>/dev/null && echo "FRAMEWORK: Next.js"
ls -la vite.config.* 2>/dev/null && echo "FRAMEWORK: Vite"
ls -la webpack.config.* 2>/dev/null && echo "FRAMEWORK: Webpack"
ls -la craco.config.* 2>/dev/null && echo "FRAMEWORK: CRA"

# 2. Check for build artifacts
ls -d .next 2>/dev/null && echo "BUILD: .next exists"
ls -d dist 2>/dev/null && echo "BUILD: dist exists"
ls -d build 2>/dev/null && echo "BUILD: build exists"

# 3. Check package manager
ls package-lock.json 2>/dev/null && echo "PKG: npm"
ls pnpm-lock.yaml 2>/dev/null && echo "PKG: pnpm"
ls yarn.lock 2>/dev/null && echo "PKG: yarn"
```

**If prerequisites not met:**
- No build directory: Run static code analysis only, note "Build artifacts not available"
- Unknown framework: Use generic patterns, note "Framework not detected"
- No package manager: Skip dependency analysis, note "No package manager detected"

## Check

**Bundle & Loading**
- Bundle size (target: <500KB initial JS)
- Code splitting implemented
- Dynamic imports for heavy components
- Tree shaking working
- No duplicate dependencies in bundle
- Images optimized (WebP, lazy loading)

**Runtime Performance**
- N+1 queries (see db-auditor)
- Expensive computations in render
- Missing memoization (useMemo, useCallback)
- Unnecessary re-renders
- Memory leaks (event listeners, subscriptions)

**Core Web Vitals**
- LCP (Largest Contentful Paint) < 2.5s
- FID (First Input Delay) < 100ms
- CLS (Cumulative Layout Shift) < 0.1
- TTFB (Time to First Byte) < 600ms

**Database & API**
- Slow queries (>100ms)
- Missing pagination
- No caching strategy
- Over-fetching data
- Missing indexes

**Infrastructure**
- No CDN for static assets
- Missing compression (gzip/brotli)
- No HTTP caching headers
- Large API payloads

## Commands (Framework-Specific)

### Next.js
```bash
# Check bundle size
cat .next/build-manifest.json 2>/dev/null | head -50 || echo "SKIP: No Next.js build"

# Analyze pages
ls -la .next/static/chunks/*.js 2>/dev/null | head -10 || echo "SKIP: No chunks"
```

### Vite
```bash
# Check bundle size
ls -la dist/assets/*.js 2>/dev/null | head -10 || echo "SKIP: No Vite build"

# Check for source maps (should not be in prod)
find dist -name "*.map" 2>/dev/null | head -5
```

### Generic (All Frameworks)
```bash
# Find large source files
find src -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null | xargs wc -l 2>/dev/null | sort -n | tail -10

# Find components without memo
grep -rn "export function\\|export const" src --include="*.tsx" --include="*.jsx" 2>/dev/null | grep -v "memo\\|React.memo" | head -10

# Find missing useCallback/useMemo
grep -rn "onClick={\\s*(" src --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10

# Find console.time/performance markers
grep -rn "console.time\\|performance.mark" src --include="*.ts" --include="*.js" 2>/dev/null

# Image analysis
find . -path ./node_modules -prune -o \\( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" \\) -print 2>/dev/null | head -20

# Check for heavy dependencies
grep -E "moment|lodash|jquery|@material-ui" package.json 2>/dev/null && echo "WARNING: Heavy dependencies detected"
```

## Output

```markdown
# Performance Audit

---
agent: perf-auditor
status: [COMPLETE|PARTIAL|SKIPPED]
timestamp: [ISO timestamp]
duration: [X seconds]
findings: [X]
framework_detected: [framework]
build_available: [true|false]
errors: [list any errors]
skipped_checks: [list checks that couldn't run]
---

## Summary
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| Initial JS | X KB | <500KB | PASS/FAIL/UNKNOWN |
| LCP | X.Xs | <2.5s | PASS/FAIL/UNKNOWN |
| FID | Xms | <100ms | PASS/FAIL/UNKNOWN |
| CLS | X.XX | <0.1 | PASS/FAIL/UNKNOWN |

**Performance Score:** X/100 (estimated)
**Analysis Mode:** Full (with build) | Static (code only)

## Critical Issues

### PERF-001: Bundle Too Large
**Current:** 1.2MB initial JS
**Target:** <500KB
**Breakdown:**
```
- vendor.js: 600KB
- main.js: 400KB
- pages/dashboard.js: 200KB
```
**Fix:**
1. Dynamic import for dashboard: `const Dashboard = dynamic(() => import('./Dashboard'))`
2. Replace moment.js (300KB) with date-fns (30KB)
3. Enable tree shaking for lodash

### PERF-002: Unoptimized Images
**Files:**
- `public/hero.png` - 2.4MB
- `public/product-1.jpg` - 800KB
**Fix:**
1. Convert to WebP (80% smaller)
2. Add responsive sizes
3. Implement lazy loading

### PERF-003: N+1 Query in Dashboard
**File:** `src/pages/dashboard.tsx:45`
**Issue:** Fetching user data in loop
**Impact:** 100 users = 101 queries, ~2s load time
**Fix:** Use include/eager loading

## High Priority

### PERF-004: Missing React.memo on List Items
**File:** `src/components/ProductCard.tsx`
**Issue:** Re-renders on every parent render
**Impact:** Slow list scrolling
**Fix:**
```typescript
export const ProductCard = React.memo(({ product }) => {
  // ...
});
```

### PERF-005: Inline Function in JSX
**File:** `src/components/Form.tsx:23`
**Issue:** New function created every render
```tsx
<button onClick={() => handleSubmit(data)}>  // Bad
```
**Fix:**
```tsx
const onSubmit = useCallback(() => handleSubmit(data), [data]);
<button onClick={onSubmit}>  // Good
```

### PERF-006: Missing Pagination
**File:** `src/api/products.ts:15`
**Issue:** Fetching all 10,000 products at once
**Impact:** 5s API response, browser freeze
**Fix:** Add limit/offset pagination

## Medium Priority

### PERF-007: No HTTP Caching
**Issue:** Static assets have no cache headers
**Fix:** Add cache headers in next.config.js or CDN

### PERF-008: Synchronous Data Fetching
**File:** `src/pages/index.tsx`
**Issue:** Blocking render on data fetch
**Fix:** Use Suspense with streaming

## Optimization Checklist

### Quick Wins
- [ ] Enable gzip/brotli compression
- [ ] Add lazy loading to images
- [ ] Memoize expensive components
- [ ] Add pagination to lists

### Medium Effort
- [ ] Implement code splitting
- [ ] Replace heavy dependencies
- [ ] Add Redis caching for APIs
- [ ] Optimize database queries

### Long Term
- [ ] Set up CDN
- [ ] Implement service worker
- [ ] Add performance monitoring
- [ ] Establish performance budget

## Recommended Tools

- **Bundle analysis:** `npm run build && npx @next/bundle-analyzer`
- **Lighthouse:** `npx lighthouse https://your-site.com`
- **Query profiling:** Enable slow query log in database
```

## Execution Logging

After completing, append to `.claude/audits/EXECUTION_LOG.md`:
```
| [timestamp] | perf-auditor | [status] | [duration] | [findings] | [errors] |
```

## Output Verification

Before completing:
1. Verify `.claude/audits/AUDIT_PERF.md` was created
2. Verify file has content beyond headers
3. If no issues found, write "No performance issues detected" (not empty file)

Focus on issues with measurable impact. Include before/after expectations for fixes.

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/perf-auditor) · https://claudary.paisolsolutions.com