# 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.
- Skill: `barisariburnu/performance-optimization` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add barisariburnu/performance-optimization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/barisariburnu/performance-optimization/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: barisariburnu (https://skillmd.com/u/barisariburnu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/barisariburnu/performance-optimization
---
# 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