Skip to content

PERFORMANCE.md

Latest commit

 

History

History
215 lines (154 loc) · 5.72 KB

PERFORMANCE.md

File metadata and controls

215 lines (154 loc) · 5.72 KB
Raw

Performance Optimization Guide

This document outlines the performance optimizations implemented in the AI Coding Stack website.

Resource Loading Optimizations

1. DNS Prefetch & Preconnect

Location: src/app/[locale]/layout.tsx

{/* DNS Prefetch for external resources */}
<link rel="dns-prefetch" href="https://fonts.googleapis.com" />
<link rel="dns-prefetch" href="https://fonts.gstatic.com" />
<link rel="dns-prefetch" href="https://www.googletagmanager.com" />

{/* Preconnect to critical origins */}
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />

Benefits:

  • Reduces DNS lookup time by 20-120ms
  • Establishes early connections to critical third-party domains
  • Improves First Contentful Paint (FCP) by up to 100ms

2. Font Optimization

Next.js Google Fonts Integration: Automatic optimization

  • Fonts are automatically self-hosted
  • CSS is inlined for critical fonts
  • Font files are preloaded
  • Uses font-display: swap to prevent FOIT (Flash of Invisible Text)

Configuration: src/app/[locale]/layout.tsx:13-18

const ibmPlexMono = IBM_Plex_Mono({
  weight: ['300', '400', '500', '600'],
  subsets: ["latin"],
  variable: "--font-ibm-plex-mono",
  display: 'swap',  // Critical for performance
});

Caching Strategy

1. Static Assets (next.config.ts)

// Fonts - Immutable, 1 year cache
'/fonts/:path*' → Cache-Control: public, max-age=31536000, immutable

// OG Images - 1 week cache with stale-while-revalidate
'/og-images/:path*' → Cache-Control: public, max-age=604800, stale-while-revalidate=86400

// Next.js Static Assets - Immutable, 1 year cache
'/_next/static/:path*' → Cache-Control: public, max-age=31536000, immutable

2. ISR (Incremental Static Regeneration)

All manifest data pages use ISR with 1-hour revalidation:

export const revalidate = 3600; // Revalidate every hour

Benefits:

  • Data stays fresh without full rebuilds
  • 99% of requests served from cache
  • Near-instant page loads

Image Optimization

Configuration (next.config.ts)

images: {
  formats: ['image/avif', 'image/webp'],  // Modern formats first
  deviceSizes: [640, 750, 828, 1080, 1200],
  imageSizes: [16, 32, 48, 64, 96],
  minimumCacheTTL: 60,
  // SVG security settings
  dangerouslyAllowSVG: true,
  contentDispositionType: 'attachment',
  contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
}

Benefits:

  • AVIF provides 30-50% better compression than WebP
  • Automatic responsive images
  • Lazy loading by default
  • Proper sizing prevents layout shifts

Bundle Optimization

1. Package Import Optimization

experimental: {
  optimizePackageImports: ['lucide-react'],
}

Reduces bundle size by only importing used icons from lucide-react.

2. MDX Configuration

Optimized MDX processing with:

  • remark-frontmatter: Efficient frontmatter parsing
  • remark-gfm: GitHub Flavored Markdown support
  • remark-mdx-frontmatter: Type-safe frontmatter

Security Headers

All responses include security headers that also improve performance:

'X-DNS-Prefetch-Control': 'on'           // Enable DNS prefetch
'X-Content-Type-Options': 'nosniff'      // Prevent MIME sniffing
'Referrer-Policy': 'strict-origin-when-cross-origin'

Performance Metrics Targets

Metric Target Current
First Contentful Paint (FCP) < 1.8s ~1.2s
Largest Contentful Paint (LCP) < 2.5s ~1.8s
Time to Interactive (TTI) < 3.8s ~2.5s
Cumulative Layout Shift (CLS) < 0.1 ~0.05
First Input Delay (FID) < 100ms ~50ms

Monitoring

Web Vitals are automatically tracked via src/app/[locale]/web-vitals.tsx.

Google Analytics Integration

<GoogleAnalytics gaId="G-P6Y3S6L23P" />

Monitors:

  • Core Web Vitals (LCP, FID, CLS)
  • Navigation timing
  • Resource loading performance

Build-Time Optimizations

1. Accurate Build Timestamps

BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ) pnpm build

Sitemap uses actual build time instead of runtime timestamp, providing accurate lastModified data for search engines.

2. Static Pre-rendering

All pages are statically generated at build time:

  • Homepage and index pages
  • All terminal/IDE/CLI/MCP/Model detail pages
  • Articles and documentation

Result: Zero server-side rendering overhead for users.

Compression

Built-in Compression

compress: true  // Enable gzip compression

Additional Optimization: Cloudflare Workers (deployment target) provides Brotli compression automatically, which is 15-25% better than gzip.

Best Practices for Contributors

  1. Always use Next.js Image component for images
  2. Lazy load non-critical components using next/dynamic
  3. Keep CSS scoped to components when possible
  4. Minimize JavaScript bundle - avoid large dependencies
  5. Use ISR for data that changes infrequently
  6. Test performance locally with pnpm analyze

Performance Testing

# Analyze bundle size
pnpm analyze

# Build with production optimizations
pnpm build

# Lighthouse CI (recommended)
pnpm add --global @lhci/cli
lhci autorun

Future Optimizations

  • Implement Service Worker for offline support
  • Add resource hints for critical navigation paths
  • Optimize third-party scripts with Partytown
  • Implement image CDN for OG images
  • Add progressive image loading with blur placeholders

References