Caching Strategies AI Should Know

AI generates code that works. It less consistently generates code that performs well. The gap is most visible in network caching -- the patterns that prevent applications from making the same request twice. AI-generated code tends to fetch data eagerly, ignore cache headers, and rebuild state from scratch on every page load.

This isn't a model limitation. It's a context limitation. AI knows caching patterns but doesn't apply them unless prompted. When you build caching knowledge into your AI skills, the generated code is fast by default.

Key Takeaways

• HTTP cache headers are the most powerful and least used caching mechanism in AI-generated code -- adding Cache-Control headers cuts redundant requests by 80%
• Stale-while-revalidate serves cached content immediately while fetching fresh data in the background -- users see instant loads with eventual consistency
• CDN caching reduces global latency by 60-80% by serving content from edge locations near the user
• Cache invalidation is the hardest problem -- time-based expiry is simple but wasteful, event-based invalidation is precise but complex
• AI skills should include caching as a default pattern rather than requiring developers to add it after the fact

HTTP Cache Headers

The Basics Most AI Misses

Every HTTP response can include caching instructions. Browsers, CDNs, and reverse proxies all respect these instructions. Yet AI-generated API routes almost never include them.

// What AI generates
export async function GET() {
  const skills = await getSkills()
  return Response.json(skills)
}

// What AI should generate
export async function GET() {
  const skills = await getSkills()
  return Response.json(skills, {
    headers: {
      'Cache-Control': 'public, max-age=60, stale-while-revalidate=300',
    },
  })
}

The second version tells browsers and CDNs: "This response is public (cacheable by anyone), fresh for 60 seconds, and can be served stale for up to 300 seconds while fetching a fresh copy."

Cache-Control Directives

Practical Examples for AI Applications

Skill catalog (changes hourly):

Cache-Control: public, max-age=300, s-maxage=3600, stale-while-revalidate=86400

Browser caches for 5 minutes. CDN caches for 1 hour. Stale responses served for up to 24 hours while revalidating.

Skill detail page (changes rarely):

Cache-Control: public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800

Browser caches for 1 hour. CDN caches for 1 day. Stale responses served for up to 1 week.

User dashboard (personalized):

Cache-Control: private, max-age=60, stale-while-revalidate=300

Only browser caches. Fresh for 1 minute. Stale for 5 minutes.

Static assets (versioned filenames):

Cache-Control: public, max-age=31536000, immutable

Cache forever. The filename changes when content changes.

Stale-While-Revalidate

Why It Matters

Stale-while-revalidate (SWR) is the single most impactful caching pattern for user experience. It serves cached content immediately, giving users an instant response, while fetching fresh data in the background for the next request.

Without SWR, users see a loading spinner while the server fetches data. With SWR, users see content immediately. If the content has changed since last cached, the next page load shows the updated version.

Client-Side SWR

The SWR pattern is also available client-side through libraries like SWR (from Vercel) or React Query:

'use client'

import useSWR from 'swr'

const fetcher = (url: string) => fetch(url).then(r => r.json())

export function SkillStats({ skillId }: { skillId: string }) {
  const { data, error, isValidating } = useSWR(
    `/api/skills/${skillId}/stats`,
    fetcher,
    {
      revalidateOnFocus: true,
      revalidateOnReconnect: true,
      dedupingInterval: 60000, // Deduplicate requests within 60 seconds
    }
  )

  if (error) return <div>Failed to load stats</div>
  if (!data) return <StatsSkeleton />

  return (
    <div className="relative">
      {isValidating && (
        <div className="absolute top-0 right-0 w-2 h-2 bg-orange-500 rounded-full animate-pulse" />
      )}
      <p>{data.installCount} installs</p>
      <p>{data.rating}/5 rating</p>
    </div>
  )
}

The isValidating flag lets you show a subtle indicator that fresh data is being fetched, without blocking the entire UI.

Next.js Caching

Route Segment Caching

Next.js App Router provides built-in caching at the route segment level:

// Static caching (default for static pages)
export const revalidate = 3600 // Revalidate every hour

// Dynamic page with ISR
export const revalidate = 60 // Revalidate every minute

// Always dynamic
export const dynamic = 'force-dynamic'

fetch() Caching

Next.js extends the fetch API with caching options:

// Cache indefinitely (default in production)
const data = await fetch('https://api.example.com/skills')

// Revalidate every 60 seconds
const data = await fetch('https://api.example.com/skills', {
  next: { revalidate: 60 },
})

// Never cache
const data = await fetch('https://api.example.com/skills', {
  cache: 'no-store',
})

// Cache with tags for selective invalidation
const data = await fetch('https://api.example.com/skills', {
  next: { tags: ['skills-catalog'] },
})

On-Demand Revalidation

Next.js supports invalidating cached content on demand:

// In a Server Action
'use server'

import { revalidateTag, revalidatePath } from 'next/cache'

export async function installSkill(skillId: string) {
  await incrementInstallCount(skillId)

  // Invalidate all pages that show skill data
  revalidateTag('skills-catalog')

  // Or invalidate a specific path
  revalidatePath('/browse')
}

This is the most precise cache invalidation strategy: update the cache only when the data actually changes, rather than relying on time-based expiry.

CDN Caching Patterns

Edge Caching With Vercel

On Vercel, responses with Cache-Control headers are automatically cached at the edge:

export async function GET() {
  const skills = await getPopularSkills()

  return Response.json(skills, {
    headers: {
      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
      'CDN-Cache-Control': 'max-age=3600',
      'Vercel-CDN-Cache-Control': 'max-age=3600',
    },
  })
}

The s-maxage directive specifically controls CDN behavior, allowing you to set different cache durations for the CDN and the browser.

Cache Key Considerations

CDN caches key responses by URL by default. If your API returns different data based on headers (like Accept-Language or Authorization), add the Vary header:

headers: {
  'Cache-Control': 'public, max-age=300',
  'Vary': 'Accept-Language',
}

Without Vary, a Spanish user might see English content cached by a previous English user's request.

Cache Invalidation Patterns

Time-Based (Simple but Wasteful)

Cache-Control: max-age=300

Content expires after 5 minutes regardless of whether it changed. Simple but wastes bandwidth when content hasn't changed and serves stale content when it has.

Event-Based (Precise but Complex)

Invalidate when the underlying data changes:

// When a skill is updated
await updateSkill(skillId, updates)
await revalidateTag(`skill-${skillId}`)
await revalidateTag('skills-catalog')

Precise but requires tracking which caches depend on which data.

Versioned URLs (Best for Assets)

/assets/main.a1b2c3d4.js → Cache-Control: immutable

The URL changes when content changes. Old URLs remain cached forever (no invalidation needed). New URLs are fetched fresh.

This is the pattern Next.js uses for its built assets. It's also the strategy that build cache techniques leverage for faster deployments.

Building Caching Into AI Skills

Every AI skill that generates API routes or data fetching code should include caching by default. Add these instructions to your skill definitions:

## Caching Requirements

When generating API routes:
1. Always include Cache-Control headers
2. Use stale-while-revalidate for non-critical data
3. Use no-store for authenticated or sensitive endpoints
4. Use immutable for versioned static assets

When generating data fetching:
1. Use Next.js fetch caching with appropriate revalidation
2. Include cache tags for selective invalidation
3. Add on-demand revalidation in mutation handlers

FAQ

Should I cache AI API responses?

For build-time operations and deterministic inputs, yes. For user-facing features with personalized prompts, cache cautiously with short TTLs. See build cache strategies for detailed patterns.

How do I debug caching issues?

Check browser DevTools Network tab for X-Cache headers (HIT/MISS). Use curl -I to inspect response headers. Temporarily add Cache-Control: no-store to confirm the issue is caching-related.

What's the biggest caching mistake in AI-generated code?

Not caching at all. AI-generated code almost never includes Cache-Control headers, which means every request goes to the origin server even when the response hasn't changed.

How do I handle cache warming for new deployments?

Make a few representative requests immediately after deployment to populate the CDN cache. Some teams automate this with a post-deployment script that hits the most popular pages.

Can caching cause security issues?

Yes, if you cache private data with public headers. Always use private or no-store for authenticated responses. Never cache responses that contain user-specific data with public cache headers.

Sources

• MDN HTTP Caching -- Comprehensive HTTP caching reference
• Next.js Caching Documentation -- Framework-specific caching patterns
• Vercel Edge Network -- CDN caching on Vercel
• web.dev: HTTP Cache -- Google's caching best practices guide

Explore production-ready AI skills at aiskill.market/browse or submit your own skill to the marketplace.