---
name: performance
source: botcore
description: >
  Optimize bundle size, Core Web Vitals, and runtime performance.
  Use when bundle size exceeds thresholds, users report slowness, or before major releases.
version: "2.1.0"
triggers:
  - LCP
  - INP
  - CLS
  - bundle size
  - Lighthouse
  - performance
  - slow
  - optimize
---

# Performance

Best practices for web performance optimization.

## When to Use

- Bundle size exceeds thresholds
- Core Web Vitals need improvement
- Users report slowness
- Before major releases

## Workflow

1. **Measure** — Get baseline metrics
2. **Analyze** — Identify bottlenecks
3. **Optimize** — Apply targeted fixes
4. **Verify** — Confirm improvements
5. **Monitor** — Track over time

## Core Web Vitals Targets

| Metric | Good | Needs Work | Poor |
|--------|------|------------|------|
| LCP | < 2.5s | 2.5-4.0s | > 4.0s |
| INP | < 200ms | 200-500ms | > 500ms |
| CLS | < 0.1 | 0.1-0.25 | > 0.25 |

## Bundle Size Targets

| Type | Target | Warning |
|------|--------|---------|
| Initial JS (gzip) | < 100KB | > 150KB |
| Total JS (gzip) | < 300KB | > 400KB |
| Critical CSS | < 50KB | > 75KB |

## Optimization Patterns

```typescript
// Code splitting with dynamic imports
const HeavyComponent = await import('./HeavyComponent');

// Lazy loading images
<img loading="lazy" src="below-fold-image.jpg" />

// Breaking up long tasks (INP)
async function yieldToMain() {
  if (navigator.scheduling?.isInputPending?.()) {
    await new Promise(r => setTimeout(r, 0));
  }
}

// Preload critical assets
<link rel="preload" href="critical.css" as="style" />
```

## Optimization Checklist

- [ ] Bundle under target size
- [ ] Images optimized (WebP, lazy load)
- [ ] Code splitting implemented
- [ ] No render-blocking resources
- [ ] CSS above-the-fold inlined
- [ ] Third-party scripts deferred

## Anti-Patterns

| Avoid | Instead |
|-------|---------|
| Importing entire libraries | Import specific functions |
| Synchronous heavy operations | Use web workers |
| Layout thrashing | Batch DOM reads/writes |
| Unoptimized images | WebP + responsive images |

## Detailed References

- `{baseDir}/references/core-web-vitals.md` — LCP, INP, CLS
- `{baseDir}/references/bundle-optimization.md` — Bundle size
- `{baseDir}/references/lazy-loading.md` — Lazy patterns
