Caching Public Data

Edge Caching Strategy

Edge caching distributes content globally through CDN nodes. Users receive responses from nearby locations within milliseconds. Origin servers handle fewer requests, reducing load and costs.

Security-First Caching Helpers

The framework provides @workspace/security helpers that enforce correct caching behavior:

import { securePublicJson } from '@workspace/security';

export async function GET() {
  const products = await fetchProducts();

  return securePublicJson(products, { maxAge: 300 });
}

import { secureUserJson } from '@workspace/security';

export async function GET(req: NextRequest) {
  const session = await getCurrentSession();
  const userData = await fetchUserProfile(session.userId);

  return secureUserJson(userData);
}

import { secureErrorJson } from '@workspace/security';

export async function GET() {
  try {
    const data = await riskyOperation();
    return securePublicJson(data, { maxAge: 60 });
  } catch (error) {
    return secureErrorJson(
      { message: 'Operation failed', code: 'SERVER_ERROR' },
      { status: 500 }
    );
  }
}

Real Implementation Example

The support ticket API demonstrates proper caching discipline:

import { secureUserJson, secureErrorJson } from '@workspace/security';

export const revalidate = 0;
export const dynamic = "force-dynamic";
export const fetchCache = "force-no-store";

export async function POST(req: NextRequest) {
  try {
    await requireSession();
    const body = await parseRequestBody(req);
    const token = await getConvexTokenOrThrow();

    const ticketId = await fetchMutation(
      api.support.createSupportTicket,
      body,
      { token }
    );

    return secureUserJson(
      { success: true, ticketId },
      { status: 201 }
    );
  } catch (error) {
    return secureErrorJson(
      { message: error.message, code: error.code },
      { status: getHttpStatus(error) }
    );
  }
}

This route:

Choosing Cache Durations

Different content types require different maxAge values:

Identifying Cacheable Content

Public data that all users see identically benefits from edge caching:

Stale-While-Revalidate Pattern

Advanced caching strategies serve cached content while updating in the background:

export async function GET() {
  const products = await fetchProducts();

  return securePublicJson(products, {
    maxAge: 300,        // Fresh for 5 minutes
    swr: 3600          // Serve stale for 1 hour while revalidating
  });
}

This pattern:

1. Serves cached content immediately (even if stale)
2. Triggers background revalidation
3. Updates cache with fresh data
4. Next request receives updated content

Users experience instant responses while data stays reasonably fresh.

Page-Level Caching with Revalidation

Next.js provides page-level caching through route segment config:

export const revalidate = 600; // Regenerate static HTML every 10 minutes

export default async function HomePage() {
  return <HeroSection />;
}

This configuration:

• Generates static HTML at build time
• Serves from edge with instant response times
• Regenerates every 10 minutes to keep content fresh
• Eliminates server requests for cached pages

The marketing site uses this pattern extensively. Static pages serve instantly while periodic regeneration ensures content freshness.

Monitoring Cache Effectiveness

Track cache performance through CDN analytics and response headers:

curl -I https://your-app.com/api/products

Cache-Control: public, max-age=300
Vary: Accept-Encoding

Common Caching Mistakes

Next Steps