| name | 07-performance-scalability |
| description | Use when auditing or improving speed, responsiveness, Core Web Vitals, caching, database performance, API response times, image optimization, bundle size, rendering strategy, and launch scalability. |
Performance and Scalability
Mission
Make the system fast enough for real users, real devices, real data volume, and launch traffic. AI-generated apps often work in localhost while hiding huge bundles, unoptimized images, unindexed queries, zero caching, and fragile serverless/database behavior.
Use when
- The user asks about performance, scaling, slow pages, launch readiness, PageSpeed, Core Web Vitals, Supabase performance, Vercel limits, API latency, or bundle size.
Targets
- LCP under 2.5s.
- INP under 200ms.
- CLS under 0.1.
- First Load JS ideally under 200KB for typical pages.
- List queries paginated.
- External calls have explicit timeouts.
- Serverless database connections use pooling where applicable.
Workflow
1. Identify framework and build profile
cat package.json
npm run build 2>/tmp/build.log || pnpm build 2>/tmp/build.log || yarn build 2>/tmp/build.log
cat /tmp/build.log | tail -120
Look for route sizes, first-load JS, static/dynamic rendering, and build warnings.
2. Audit Core Web Vitals and loading UX
If URL is available, use PageSpeed/Lighthouse or provider analytics. In code, search:
rg -n 'loading\.tsx|Suspense|skeleton|ErrorBoundary|error\.tsx|priority=|next/image|<img|layout shift|font-display' app pages src 2>/dev/null
Required:
- skeleton/loading states for slow routes;
- error boundaries;
- stable image dimensions;
- font loading does not cause major layout shifts.
3. Audit images
find public app src -type f \( -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.webp' -o -iname '*.gif' \) -size +500k -print 2>/dev/null
rg -n '<img|next/image|Image from' app pages src 2>/dev/null
Required:
- use
next/image or equivalent optimizer;
- width/height/alt set;
- above-the-fold images prioritized;
- large images compressed and modern formats preferred;
- lazy loading below the fold.
4. Audit bundle and client boundaries
rg -n '"use client"|use client|dynamic\(|import\(|from "lodash"|from "moment"|from "lucide-react"|from "@mui"|from "framer-motion"|from "recharts"' app pages src 2>/dev/null
Red flags:
use client at layout/root level without need;- giant libraries imported into common paths;
- charts/editors/maps loaded on first page load;
- no dynamic import for heavy components.
5. Audit caching and rendering strategy
rg -n 'revalidate|cache:|force-dynamic|no-store|s-maxage|Cache-Control|SWR|useQuery|React Query|fetch\(' app pages src server 2>/dev/null
Required:
- SSG/ISR for stable pages;
- SSR only where freshness requires it;
- SWR/React Query for client-side data fetching;
- API cache headers for cacheable responses;
- avoid
no-store everywhere.
6. Audit database performance
rg -n 'select\(\*\)|findMany|limit|range\(|order\(|where:|include:|for \(.*await|Promise\.all|user_id|organization_id|tenantId|created_at|index|@@index|CREATE INDEX' app pages src server prisma supabase db 2>/dev/null
Required:
- pagination on all list queries;
- indexes on frequent filters;
- no N+1 loops;
- no full-table
select('*') without filters;
- connection pooling in serverless.
7. Audit API performance
Search external calls and payload size:
rg -n 'fetch\(|axios|openai|anthropic|stripe|resend|sendgrid|AbortController|timeout|stream|ReadableStream|select\(\*\)' app pages src server 2>/dev/null
Required:
- explicit timeouts;
- streaming for long AI responses;
- minimal payloads;
- background jobs for heavy work;
- avoid blocking user requests on non-critical operations.
8. Basic load readiness
If allowed:
npx artillery quick --count 10 --num 5 https://example.com
Or provide a k6 script for the user to run. Record provider limits and expected launch traffic.
Output contract
# Performance and Scalability Report
## Executive summary
## Metrics / build observations
## Findings
| Severity | Area | Evidence | Impact | Fix | Verification |
|---|---|---|---|---|---|
## Quick wins
## Launch-readiness risks
## Changes made
## Remaining risks
Stop criteria
Stop and warn before load-testing production at meaningful volume, changing cache semantics on critical data, or modifying database indexes/migrations without backup/approval.
