---
name: performance-optimization
description: Performance optimization guidelines for web development including server-side rendering, CSS best practices, and JavaScript optimization
---

# Performance Optimization

Apply these performance optimization principles when developing web applications, themes, and frontend interfaces.

## Core Performance Principles

- Prioritize server-side rendering as a first principle, as opposed to client-side JavaScript
- Minimize client-side JavaScript to reduce bundle size and improve Time to Interactive
- Optimize for Core Web Vitals: LCP, FID, and CLS
- Measure performance continuously and establish baselines
- Consider performance impact of every architectural decision

## Server-Side Rendering

- Render content server-side whenever possible
- Use streaming rendering for faster Time to First Byte
- Implement proper caching strategies for rendered content
- Avoid blocking resources that delay rendering
- Pre-render static content where applicable

## CSS Best Practices

### Selector Efficiency
- Avoid ID selectors for styling; use classes instead
- Maintain specificity at 0 1 0 where possible
- Avoid deep nesting of selectors (max 3 levels)
- Use BEM or similar naming conventions for clarity
- Prefer class selectors over element selectors

### CSS Organization
- Use CSS variables for colors, spacing, and repeated values
- Group related styles logically
- Remove unused CSS to reduce payload
- Consider critical CSS inlining for above-the-fold content
- Use CSS containment for complex layouts

### Layout Performance
- Avoid layout thrashing (forced synchronous layouts)
- Use transform and opacity for animations (GPU accelerated)
- Minimize paint and composite operations
- Use will-change sparingly and intentionally
- Prefer flexbox and grid over floats and positioning

## JavaScript Optimization

### Code Organization
- Use the module pattern for code organization
- Prefix private methods with appropriate indicators
- Prefer const over let; avoid var
- Avoid external dependencies when native APIs suffice
- Split code into logical, loadable chunks

### Loading Strategies
- Defer non-critical JavaScript
- Use async loading for independent scripts
- Implement code splitting for large applications
- Lazy load components and routes
- Preload critical resources

### Runtime Performance
- Debounce and throttle event handlers appropriately
- Use requestAnimationFrame for visual updates
- Avoid long-running synchronous operations
- Implement efficient DOM manipulation patterns
- Use Web Workers for CPU-intensive tasks

## Asset Optimization

### Images
- Use modern formats (WebP, AVIF) with fallbacks
- Implement responsive images with srcset
- Lazy load below-the-fold images
- Optimize and compress all images
- Use appropriate image dimensions

### Fonts
- Subset fonts to include only needed characters
- Use font-display: swap for better perceived performance
- Preload critical fonts
- Limit the number of font variations
- Consider system fonts for non-branded text

## Caching Strategies

- Implement appropriate cache headers for static assets
- Use versioned filenames for cache busting
- Configure CDN caching effectively
- Implement service workers for offline support
- Cache API responses where appropriate

## Architecture Patterns

### Theme and Component Architecture
- Organize code into logical sections and blocks
- Use proper folder structure for maintainability
- Implement clear separation of concerns
- Create reusable, composable components
- Document component APIs and usage

### Configuration and Settings
- Organize settings logically with clear groupings
- Use clear, descriptive naming conventions
- Implement conditional logic to reduce complexity
- Provide sensible defaults
- Validate configuration at build time

## Internationalization Performance

- Ensure all text is translatable
- Load translations efficiently (split by locale)
- Use proper locale detection
- Cache translated content appropriately
- Consider right-to-left (RTL) layout implications

## Measurement and Monitoring

- Use Real User Monitoring (RUM) for production insights
- Set up synthetic monitoring for baseline tracking
- Monitor Core Web Vitals continuously
- Track performance budgets in CI/CD
- Analyze and act on performance regressions

## Database Performance

- Optimize queries and use proper indexing
- Implement connection pooling
- Use caching for frequently accessed data
- Paginate large result sets
- Monitor slow queries and optimize regularly