# Performance Optimization
> Complete performance optimization guide for Next.js applications including frontend, backend, database, caching, and general optimization strategies. Use when improving performance, reducing bundle size, optimizing queries, or implementing caching. Use when this capability is needed.
- Skill: `tomevault-io/performance-optimization-15` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/performance-optimization-15`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/performance-optimization-15/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/performance-optimization-15
---
# Performance Optimization Skill
**Skill Location**: `{project_path}/skills/performance-optimization/`
Comprehensive guide for optimizing Next.js applications, optimized for minimal token usage while covering all performance aspects.
---
## When to Use This Skill (Trigger Patterns)
**MUST apply this skill when:**
- Optimizing page load times
- Reducing bundle size
- Improving database query performance
- Implementing caching strategies
- Optimizing API responses
- Reducing client-side JavaScript
- Improving Core Web Vitals
**Trigger phrases:**
- "optimize performance"
- "reduce bundle size"
- "improve load time"
- "make it faster"
- "implement caching"
- "optimize database queries"
---
## Performance Metrics
```
Core Web Vitals:
- LCP (Largest Contentful Paint): < 2.5s
- FID (First Input Delay): < 100ms
- CLS (Cumulative Layout Shift): < 0.1
- FCP (First Contentful Paint): < 1.8s
- TTI (Time to Interactive): < 3.8s
```
---
## Token-Saving Strategies
### 1. Focus on Specific Optimizations
**❌ INEFFICIENT:**
```
"Performance is important because users expect fast loading..."
```
**✅ EFFICIENT:**
```
// Dynamic import for code splitting
```
### 2. Use Standard Patterns
Don't explain:
- Why optimization is important
- What LCP, FID, CLS mean
- Basic performance concepts
Focus on:
- Implementation patterns
- Specific optimizations
- Tool configurations
### 3. Code Examples Over Explanations
Show code, not theory.
---
## Frontend Optimization
### 1. Code Splitting
```typescript
// Dynamic imports for heavy components
import dynamic from 'next/dynamic'
const ChartComponent = dynamic(
() => import('@/components/features/Chart'),
{ loading: () => Loading chart...
}
)
const HeavyModal = dynamic(
() => import('@/components/features/HeavyModal'),
{ ssr: false } // Don't render on server
)
// Route-based code splitting (automatic)
// Each page in /app is automatically split
```
### 2. Image Optimization
```typescript
import Image from 'next/image'
// Optimized image
// Responsive images
```
### 3. Font Optimization
```typescript
// next.config.ts
module.exports = {
optimizeFonts: true
}
// Use next/font
import { Inter } from 'next/font/google'
const inter = Inter({
subsets: ['latin'],
display: 'swap',
variable: '--font-inter'
})
export default function RootLayout({
children
}: {
children: React.ReactNode
}) {
return (
{children}
)
}
```
### 4. Lazy Loading Components
```typescript
// Intersection Observer for lazy loading
'use client'
import { useRef, useEffect, useState } from 'react'
function LazyComponent({ children }: { children: React.ReactNode }) {
const [isVisible, setIsVisible] = useState(false)
const ref = useRef(null)
useEffect(() => {
const observer = new IntersectionObserver(([entry]) => {
if (entry.isIntersecting) {
setIsVisible(true)
observer.disconnect()
}
})
if (ref.current) {
observer.observe(ref.current)
}
return () => observer.disconnect()
}, [])
return (
{isVisible ? children :
Loading...
}
{sum}
}
// Prevent unnecessary re-renders
function Parent({ items }: { items: Item[] }) {
const handleClick = useCallback((id: string) => {
console.log('Clicked:', id)
}, [])
return (
<>
{items.map(item => (
))}
)
}
// Memo component
import { memo } from 'react'
const Child = memo(function Child({
item,
onClick
}: {
item: Item
onClick: (id: string) => void
}) {
return
})
```
---
## Backend Optimization
### 1. Server Components
```typescript
// Server components - no JS sent to client
export default async function UserList() {
const users = await db.user.findMany()
return (
{users.map(user => (
{user.name}
))}
Loading...
return {/* Render */}
}
```
### 2. Client State with Zustand
```typescript
// Minimal state, only what's needed
interface UserStore {
user: User | null
setUser: (user: User | null) => void
}
export const useUserStore = create((set) => ({
user: null,
setUser: (user) => set({ user })
}))
```
---
## Asset Optimization
### 1. CSS Optimization
```css
/* Use CSS variables for theming */
:root {
--color-primary: #000;
--spacing-sm: 8px;
}
/* Tailwind CSS purges unused styles in production */
/* next.config.ts */
module.exports = {
tailwindcss: {
content: ['./src/**/*.{js,ts,jsx,tsx}']
}
}
```
### 2. Bundle Analysis
```typescript
// next.config.ts
const withBundleAnalyzer = require('@next/bundle-analyzer')({
enabled: process.env.ANALYZE === 'true'
})
module.exports = withBundleAnalyzer({
// ...config
})
// Analyze bundle
bun run build
ANALYZE=true bun run build
```
### 3. Tree Shaking
```typescript
// Import only what you need
// Bad
import _ from 'lodash'
// Good
import debounce from 'lodash/debounce'
// Better - use native or smaller libraries
import { debounce } from '@/lib/utils'
```
---
## Common Optimizations
### 1. Debounce and Throttle
```typescript
// Debounce
function debounce any>(
func: T,
wait: number
): (...args: Parameters) => void {
let timeout: NodeJS.Timeout
return (...args: Parameters) => {
clearTimeout(timeout)
timeout = setTimeout(() => func(...args), wait)
}
}
// Throttle
function throttle any>(
func: T,
limit: number
): (...args: Parameters) => void {
let inThrottle: boolean
return (...args: Parameters) => {
if (!inThrottle) {
func(...args)
inThrottle = true
setTimeout(() => (inThrottle = false), limit)
}
}
}
// Usage
const debouncedSearch = debounce((query: string) => {
searchUsers(query)
}, 300)
debouncedSearch(e.target.value)} />
```
### 2. Virtualization
```typescript
// Use react-window or react-virtualized for long lists
import { FixedSizeList } from 'react-window'
function VirtualList({ items }: { items: any[] }) {
const Row = ({ index, style }: { index: number; style: any }) => (
{items[index].name}
)
return (
{Row}
)
}
```
### 3. Lazy Loading Images
```typescript
'use client'
import { useState, useRef } from 'react'
function LazyImage({ src, alt }: { src: string; alt: string }) {
const [isLoaded, setIsLoaded] = useState(false)
const imgRef = useRef(null)
return (
setIsLoaded(true)}
style={{ opacity: isLoaded ? 1 : 0, transition: 'opacity 0.3s' }}
/>
)
}
```
---
## Performance Monitoring
### 1. Core Web Vitals
```typescript
'use client'
import { useReportWebVitals } from 'next/web-vitals'
export function WebVitals() {
useReportWebVitals((metric) => {
// Send to analytics
console.log(metric)
if (metric.rating === 'poor') {
// Log poor performance
console.warn(`${metric.name} is poor: ${metric.value}`)
}
})
return null
}
// In app/layout.tsx
import { WebVitals } from '@/components/WebVitals'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
### 2. Performance API
```typescript
// Measure performance
function measurePerformance() {
const startTime = performance.now()
// Do something
expensiveOperation()
const endTime = performance.now()
console.log(`Operation took ${endTime - startTime}ms`)
}
```
---
## Common Pitfalls & Solutions
### ❌ Problem: Large initial bundle
**✅ Solution:** Code splitting and dynamic imports
```typescript
import dynamic from 'next/dynamic'
const HeavyComponent = dynamic(
() => import('@/components/Heavy'),
{ ssr: false }
)
```
### ❌ Problem: N+1 query problem
**✅ Solution:** Use include/select or batch queries
```typescript
// Bad
const posts = await db.post.findMany()
for (const post of posts) {
const author = await db.user.findUnique({ where: { id: post.authorId }})
}
// Good
const posts = await db.post.findMany({
include: { author: true }
})
```
### ❌ Problem: Unnecessary re-renders
**✅ Solution:** Use memo and useCallback
```typescript
const memoizedValue = useMemo(() => expensiveCalculation(data), [data])
const memoizedCallback = useCallback(() => handleEvent(id), [id])
```
### ❌ Problem: Large images
**✅ Solution:** Use next/image with optimization
```typescript
```
---
## Token-Efficient Prompt Templates
### Optimize Page
```
Optimize :
- Dynamic imports for heavy components
- Image optimization with next/image
- Server components for static content
- Implement caching
```
### Optimize Database
```
Optimize database queries:
- Add indexes for frequent queries
- Select only needed fields
- Use pagination
- Batch operations
```
### Reduce Bundle
```
Reduce bundle size:
- Dynamic imports
- Tree shaking
- Remove unused dependencies
- Analyze bundle with @next/bundle-analyzer
```
---
## Quick Commands
```typescript
// Analyze bundle
ANALYZE=true bun run build
// Check bundle size
bun run build
# Check output for bundle sizes
// Performance testing
# Use Lighthouse Chrome extension
# Use PageSpeed Insights: https://pagespeed.web.dev/
// Database query analysis
bunx prisma studio
# Check query performance
```
---
## Optimization Checklist
### Frontend
- [ ] Code splitting for heavy components
- [ ] Image optimization with next/image
- [ ] Font optimization with next/font
- [ ] Memoization for expensive operations
- [ ] Virtualization for long lists
- [ ] Lazy loading for images and components
- [ ] CSS optimization and purging
### Backend
- [ ] Server components where possible
- [ ] API response optimization
- [ ] Caching strategies
- [ ] Static generation for static pages
- [ ] Incremental static regeneration
### Database
- [ ] Indexes for frequent queries
- [ ] Select only needed fields
- [ ] Pagination for large datasets
- [ ] Batch operations
- [ ] Query optimization
### General
- [ ] Monitor Core Web Vitals
- [ ] Regular bundle analysis
- [ ] Performance monitoring
- [ ] Regular performance audits
---
## Important Reminders
1. **Measure first** - Profile before optimizing
2. **Critical path** - Optimize what matters most
3. **Server components** - Default to server components
4. **Code splitting** - Use dynamic imports
5. **Image optimization** - Always use next/image
6. **Database indexes** - Add for frequent queries
7. **Caching** - Cache where possible
8. **Monitor** - Track performance over time
---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/barisariburnu) — claim your Tome and manage your conversions.