Optimize

Optimize

Reduce waste and improve efficiency. Only optimize after you have real users and real problems — premature optimization is the most common waste of founder time.

This skill is for making existing things faster and leaner. For building features, use build. For fixing bugs, use debug. For monitoring performance in production, use monitor. For database schema design, use database.

Workflow

Optimize your app:
- [ ] Measure first — get actual numbers (page load, API speed, bundle size)
- [ ] Speed — fix the slowest page or API endpoint
- [ ] Dependencies — update packages, remove unused ones
- [ ] Database — clean orphaned data, optimize slow queries
- [ ] Code — remove dead code and unused files
- [ ] Re-measure — verify improvements with numbers

When to Optimize (and When NOT To)

Don't optimize when:

• Building your MVP
• Fewer than ~100 active users
• Everything works fine
• You haven't measured the problem

Optimize when:

• Users complain about slowness (Speed)
• Bundle size warnings or security alerts appear (Dependencies)
• App noticeably slower than when you launched (Speed/Database)
• You're paying for hosting you shouldn't need (Speed/Database)

Rule: Make it work → get users → measure → THEN make it lean.

---

Priority Order

When multiple things need work:

1. Speed — Users feel this immediately. Slow = churn. 2. Dependencies — Security vulnerabilities are urgent. Bundle bloat affects speed. 3. Database — Affects long-term performance and hosting costs. 4. Code — Affects maintainability. Lowest user impact.

---

Speed Optimization

Targets

Step 1: Measure

Claude Code (can measure directly):

Audit app performance:
- Measure page load times for the 3 most important pages
- Log API response times for the 5 most-used endpoints
- Identify the slowest database queries
- Check total bundle size
Report findings with specific numbers.

Lovable / Replit / Cursor (measure manually first): 1. Open your app in Chrome → Right-click → Inspect → Network tab → Reload 2. Note the "Load" time at the bottom — that's your page load time 3. Click a button that calls your API — note the request time in Network tab 4. Then paste findings into chat:

My app's performance numbers:
- Homepage loads in [X] seconds
- [Main feature] API takes [X] seconds
- [Other page] loads in [X] seconds
What's slow and how do I fix it?

Step 2: Fix

Tell AI:

Optimize these performance issues:
[paste audit findings]

Apply fixes in this order:
1. Add caching for slow API calls
2. Add database indexes for slow queries
3. Optimize and lazy-load images
4. Code split large bundles
Run build and tests after each fix.

Step 3: Prevent

Tell AI:

Add performance monitoring:
- Log API calls > 500ms
- Log database queries > 100ms
- Alert if page load > 3s

See PERFORMANCE-CHECKS.md for detailed testing methods.

---

Dependencies Optimization

The most relevant optimization at any stage — even pre-launch.

Signs You Need This

• Security vulnerability warnings when you run npm install
• Bundle size > 500KB
• "What does this package do?"

Audit

Tell AI:

Audit dependencies:
- List packages not imported anywhere in code
- List packages with security vulnerabilities
- Analyze bundle size by package
- Find packages with lighter alternatives

Report: package name, size impact, and recommendation.

Fix

Tell AI:

Clean up dependencies:
[paste audit findings]

Steps:
- Remove unused packages from package.json
- Update packages with security vulnerabilities
- Replace heavy packages with lighter alternatives
After changes: delete node_modules, fresh npm install, run build and tests.

Common replacements:

Prevent

Tell AI:

Set up dependency hygiene:
- Add npm audit to CI pipeline
- Configure Dependabot for automatic security updates

See DEPENDENCIES.md for detailed patterns.

---

Database Optimization

When this matters: After months of real usage, when queries slow down or hosting costs climb.

Signs You Need This

• Pages that were fast are now slow
• Database hosting costs increasing
• Queries timing out under load

Audit and Fix

Tell AI:

Audit database for optimization opportunities:
- Find missing indexes on frequently queried columns
- Find slow queries (> 100ms)
- Find orphaned records (foreign keys pointing to deleted rows)
- Find tables with no recent reads/writes

For each issue, apply the fix:
- Add indexes for slow queries
- Set up ON DELETE CASCADE for dependent records
- Create cleanup job for orphaned/soft-deleted records (> 90 days)
Always backup before making schema changes.

---

Code Cleanup

When this matters: After your codebase has grown significantly through AI-assisted iteration. Multiple rounds of "build feature, rebuild feature" leave dead code.

Signs You Need This

• Files you don't recognize
• Components that aren't used anywhere
• "I'm afraid to delete this"

Audit and Fix

Tell AI:

Audit codebase for unused code:
- Find components not imported anywhere
- Find functions never called
- Find commented-out code blocks
For each: verify nothing references it, then remove it.

For duplicate/similar code, use **dry** — it covers deduplication across UI, database, and logic.
Run build and tests after cleanup.

Safety rule: If unsure, comment out first and test. Delete after confirming nothing breaks.

---

Common Mistakes

---

Success Looks Like

After optimization, you should see:

• Pages load < 3 seconds
• Zero security vulnerabilities in dependencies
• No obviously unused packages
• Database queries respond < 100ms
• Automated checks catch future regressions

---

Related Skills

• monitor — Track performance in production after optimizing
• debug — Fix broken things (optimize fixes slow things)
• deploy — Hosting configuration affects performance
• database — Schema design and query optimization
• dry — Find and eliminate code duplication across UI, database, and logic
• build — Feature development (optimize after building, not during)

Dependencies Optimization

Detailed patterns for reducing package bloat and managing dependencies.

---

Why Dependencies Accumulate

When building with AI tools:

• AI adds packages to solve problems quickly
• Experiments leave unused packages behind
• Multiple packages for same purpose
• Transitive dependencies multiply

Result: Slow installs, large bundles, security vulnerabilities.

---

Types of Dependency Waste

1. Unused Packages

Packages in package.json that aren't imported anywhere.

How to find:

npx depcheck

Common unused packages:

• Packages from abandoned features
• Packages replaced by alternatives
• Dev tools no longer used
• Packages added "just in case"

2. Duplicate Packages

Same package at different versions, or multiple packages doing the same thing.

How to find:

npm ls --all | grep -E "^├|^│.*├"

Common duplications:

• lodash + lodash-es + underscore
• moment + dayjs + date-fns
• axios + node-fetch + got
• uuid + nanoid + cuid

3. Heavy Packages

Packages that add significant bundle size.

How to find:

npx webpack-bundle-analyzer
# or
npx source-map-explorer build/static/js/*.js

Common heavy packages:

4. Outdated Packages

Packages with available updates, especially security patches.

How to find:

npm outdated
npm audit

5. Dev Dependencies in Production

devDependencies that accidentally ended up in dependencies.

How to find:

Check package.json dependencies section for:
- Testing libraries (jest, mocha, cypress)
- Linters (eslint, prettier)
- Build tools (webpack, babel configs)
- Type definitions (@types/*)

---

Audit Workflow

Step 1: Check Unused

# Install depcheck
npm install -g depcheck

# Run analysis
depcheck

# Output shows:
# - Unused dependencies
# - Unused devDependencies
# - Missing dependencies

Step 2: Check Bundle Size

# Build and analyze
npm run build

# For detailed breakdown (React/webpack)
npx webpack-bundle-analyzer build/stats.json

# For Next.js
npx @next/bundle-analyzer

Step 3: Check Security

# Check for vulnerabilities
npm audit

# Check for outdated
npm outdated

# Check for deprecated
npm ls 2>&1 | grep -i deprecated

Step 4: Generate Report

Tell AI:

Analyze package.json and generate report:
- Unused packages (from depcheck output)
- Largest packages by bundle size
- Packages with security vulnerabilities
- Packages with major updates available
- Duplicate functionality packages

For each, recommend: keep, remove, or replace.

---

Safe Removal Process

For Unused Packages

# Step 1: Verify not used
grep -r "package-name" src/

# Step 2: Remove from package.json
npm uninstall package-name

# Step 3: Test
npm run build && npm test

# Step 4: If tests pass, commit

For Package Replacement

# Step 1: Install alternative
npm install dayjs

# Step 2: Update imports
# Change: import moment from 'moment'
# To: import dayjs from 'dayjs'

# Step 3: Update usage
# Change: moment().format('YYYY-MM-DD')
# To: dayjs().format('YYYY-MM-DD')

# Step 4: Remove old package
npm uninstall moment

# Step 5: Test thoroughly
npm run build && npm test

For Major Updates

# Step 1: Check changelog for breaking changes
# Visit package's GitHub releases page

# Step 2: Update one package at a time
npm install package-name@latest

# Step 3: Test
npm run build && npm test

# Step 4: Fix any breaking changes
# Step 5: Commit before next update

---

Common Replacements

Date/Time

// moment → dayjs (mostly compatible API)
import dayjs from 'dayjs';
dayjs().format('YYYY-MM-DD');

// moment → date-fns (function-based)
import { format } from 'date-fns';
format(new Date(), 'yyyy-MM-dd');

HTTP Requests

// axios → fetch
const response = await fetch('/api/data');
const data = await response.json();

// With error handling
const response = await fetch('/api/data');
if (!response.ok) throw new Error(response.statusText);
const data = await response.json();

Utilities

// lodash _.map → native
array.map(x => x.value);

// lodash _.filter → native
array.filter(x => x.active);

// lodash _.find → native
array.find(x => x.id === targetId);

// lodash _.uniq → native
[...new Set(array)];

// If you need lodash, import individual functions
import debounce from 'lodash/debounce';

UUIDs

// uuid → nanoid
import { nanoid } from 'nanoid';
const id = nanoid();

// uuid → native (browsers/Node 19+)
const id = crypto.randomUUID();

---

Prevention Patterns

Bundle Size Budget

Add to CI pipeline:

// package.json
{
  "scripts": {
    "build": "next build",
    "check-bundle": "bundlesize"
  },
  "bundlesize": [
    {
      "path": ".next/static/chunks/*.js",
      "maxSize": "200 KB"
    }
  ]
}

Dependabot

Create .github/dependabot.yml:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5

Import Cost Extension

VS Code extension that shows import size inline:

import moment from 'moment';  // 290KB
import dayjs from 'dayjs';    // 7KB

Pre-commit Check

Add to .husky/pre-commit:

#!/bin/sh
npm audit --audit-level=high
if [ $? -ne 0 ]; then
  echo "Security vulnerabilities found. Fix before committing."
  exit 1
fi

---

Package.json Hygiene

Correct Placement

{
  "dependencies": {
    // Runtime packages only
    "react": "^18.0.0",
    "next": "^14.0.0"
  },
  "devDependencies": {
    // Build/test/dev tools only
    "typescript": "^5.0.0",
    "jest": "^29.0.0",
    "eslint": "^8.0.0",
    "@types/react": "^18.0.0"
  }
}

Version Pinning

{
  "dependencies": {
    // Exact versions for critical packages
    "react": "18.2.0",

    // Caret for minor updates OK
    "lodash": "^4.17.21",

    // Never use * or latest
    "bad-practice": "*"  // DON'T DO THIS
  }
}

Lock Files

• Always commit package-lock.json (npm) or yarn.lock (yarn)
• Never delete lock file without understanding consequences
• Regenerate by deleting node_modules + lock file, then npm install

---

Cleanup Checklist

- [ ] Run depcheck for unused packages
- [ ] Run npm audit for vulnerabilities
- [ ] Run npm outdated for updates
- [ ] Analyze bundle size
- [ ] Remove unused packages
- [ ] Replace heavy packages with lighter alternatives
- [ ] Update packages with security issues
- [ ] Move dev tools to devDependencies
- [ ] Set up Dependabot
- [ ] Add bundle size check to CI
- [ ] Delete node_modules and reinstall fresh
- [ ] Verify build and tests pass

Performance Testing & Measurement

How to measure and test performance without technical expertise.

---

Browser Testing (Chrome DevTools)

Page Load Speed

Open DevTools: 1. Right-click page → Inspect 2. Click "Network" tab 3. Reload page (Cmd+R)

Check metrics:

• DOMContentLoaded: Should be < 2 seconds
• Load: Should be < 3 seconds
• Finish: All resources loaded

Red flags:

• Any single file > 1MB
• More than 50 requests on initial load
• Requests taking > 2 seconds

API Response Time

Monitor API calls: 1. Open DevTools → Network tab 2. Filter: XHR 3. Perform action (click button, load page) 4. Check time column

Targets:

• < 200ms: Excellent
• 200-500ms: Good
• 500ms-1s: Needs optimization
• > 1s: Problem

Lighthouse Score

Run Lighthouse: 1. Open DevTools 2. Click "Lighthouse" tab 3. Select "Performance" 4. Click "Generate report"

Targets:

• 90-100: Excellent
• 70-89: Good
• 50-69: Needs improvement
• < 50: Poor

Focus on:

• First Contentful Paint (< 1.8s)
• Time to Interactive (< 3.8s)
• Speed Index (< 3.4s)

---

Database Query Performance

Check Query Times

Tell AI to add logging:

Log all database queries with execution time.
Log queries taking > 100ms as warnings.
Format: [QUERY] [TIME] [SQL]

Review logs:

# Find slow queries
grep "QUERY" logs.txt | grep -v "SELECT" | sort -k2 -nr | head -20

Red flags:

• Any query > 1 second
• Same query repeated many times (N+1 problem)
• Full table scans (missing indexes)

N+1 Query Detection

Symptom:

• Loading 10 users makes 11 queries (1 for users, 1 per user for related data)

Check:

Enable query logging
Load a list page
Count queries in logs
Should be 1-3 queries total, not 1 per item

Fix with AI:

Prevent N+1 queries:
Use JOIN or eager loading
Include related data in single query
Example: User.findAll({ include: [Posts, Comments] })

---

Image Optimization

Check Image Sizes

# Check image sizes
ls -lh public/images/

# Find large images
find public/images -size +500k

Targets:

• Thumbnails: < 50KB
• Regular images: < 200KB
• Hero images: < 500KB

Check Image Format

Modern formats:

• WebP: Best compression, modern browsers
• AVIF: Better than WebP, limited support
• JPEG: Universal, good for photos
• PNG: Universal, good for graphics

Tell AI:

Convert images to WebP:
- Quality: 80%
- Fallback to JPEG for old browsers
- Serve via <picture> element

---

Bundle Size Analysis

JavaScript Bundle

Check size:

npm run build
# Look for "bundle size" in output

Targets:

• < 100KB: Excellent
• 100-200KB: Good
• 200-500KB: Large, consider optimization
• > 500KB: Too large, needs code splitting

Analyze bundle:

npm install --save-dev webpack-bundle-analyzer
npm run build -- --analyze
# Opens visualization of bundle

Code Splitting Check

Should lazy load:

• Admin pages (if regular users don't access)
• Settings/profile pages
• Large libraries (charts, editors)
• Routes not on landing page

Tell AI:

Implement code splitting:
- Lazy load routes with React.lazy()
- Dynamic import for large libraries
- Split by route, not by component

---

Caching Verification

Check Cache Headers

curl -I https://yourapp.com/api/endpoint

Look for:

Cache-Control: max-age=300

Targets:

• Static assets: max-age=31536000 (1 year)
• API data: max-age=60-300 (1-5 minutes)
• User-specific: private, max-age=60

Redis Cache Hit Rate

Tell AI to log cache hits:

Log cache hits and misses:
- "CACHE_HIT: /api/dashboard"
- "CACHE_MISS: /api/dashboard"

Calculate hit rate hourly.
Target: > 80% hit rate

---

Load Testing

Simple Load Test

Test API endpoint:

# 100 concurrent requests
for i in {1..100}; do
  curl https://yourapp.com/api/endpoint &
done
wait

# Should complete in < 10 seconds total

Artillery (For serious testing)

npm install -g artillery

# Create test.yml:
# config:
#   target: 'https://yourapp.com'
# scenarios:
#   - duration: 60
#     arrivalRate: 5
#     flow:
#       - get:
#           url: "/api/dashboard"

artillery run test.yml

Interpret results:

• Median response: < 500ms
• 95th percentile: < 1s
• No errors

---

Real User Monitoring

Basic Analytics

Track in application:

• Page load time
• API response time
• Error rates

Tell AI:

Add performance tracking:
- Measure and log page load time
- Measure API response times
- Send to analytics (aggregate, don't spam)

Free Tools

Vercel Analytics:

• Automatic for Vercel deployments
• Real user metrics
• Core Web Vitals

Cloudflare Analytics:

• Free tier includes performance metrics
• Global latency tracking

Google PageSpeed Insights:

• Free
• Tests from different locations
• Mobile and desktop scores

---

Performance Budget

Set Targets

Performance Budget:
- Page load: 3 seconds
- API response: 500ms
- Bundle size: 200KB
- Image size: 500KB max each
- Database query: 100ms

Enforce in CI/CD

Tell AI:

Add performance checks to CI:
- Fail build if bundle > 200KB
- Fail if Lighthouse score < 70
- Fail if any image > 500KB

---

Database Index Analysis

Check Existing Indexes

Tell AI:

List all database indexes.
Show table, column, and index type.

Identify Missing Indexes

Check slow query log for patterns:

• WHERE clauses on non-indexed columns
• ORDER BY on non-indexed columns
• JOIN on non-indexed foreign keys

Tell AI:

Analyze slow queries and suggest indexes.
Show CREATE INDEX statements.
Explain impact (estimated speedup).

---

Mobile Performance

Test on Real Devices

Minimum tests:

• iPhone (Safari)
• Android phone (Chrome)
• Slow 3G network (Chrome DevTools can throttle)

Mobile-Specific Issues

Check for:

• Images not responsive (serving desktop size to mobile)
• Too many fonts loaded
• Blocking JavaScript on initial load
• No lazy loading of images

Tell AI:

Optimize for mobile:
- Serve responsive images (srcset)
- Reduce font loading (subset or system fonts)
- Defer non-critical JavaScript
- Lazy load all images below fold

---

Quick Daily Checks

30-second performance check:

1. Open app in incognito mode 2. Open DevTools → Network 3. Reload page 4. Check "Load" time (< 3s?) 5. Click around, check API times (< 500ms?)

If times creeping up: Time to optimize.

---

When Numbers Don't Matter

Focus on user experience, not absolute numbers:

Good metrics but bad UX:

• Fast load but then nothing works
• Quick API but spinner shows for 5 seconds
• Small bundle but everything feels janky

Bad metrics but good UX:

• 4 second load but progressive rendering
• 800ms API but optimistic updates
• Large bundle but instant interactions

Balance: Fast technical performance + Good perceived performance.