Revalidation Strategy Planner

Analyze Next.js application routes and recommend optimal caching and revalidation strategies for performance and data freshness.

Overview

To optimize Next.js caching strategies:

Analyze route characteristics (data freshness requirements, update frequency)
Determine appropriate rendering strategy (SSG, ISR, SSR, streaming)
Configure revalidation intervals for ISR routes
Implement cache tags for on-demand revalidation
Set up streaming for progressive page loading

Rendering Strategies

Static Site Generation (SSG)

To use SSG for rarely changing content:

typescript

// app/about/page.tsx
export default async function AboutPage() {
  // Generated at build time, no revalidation
  return <div>About Us</div>;
}

Best for:

Marketing pages
Documentation
Static content that rarely changes

Incremental Static Regeneration (ISR)

To use ISR for periodically updated content:

typescript

// app/entities/[id]/page.tsx
export const revalidate = 3600; // Revalidate every hour

export default async function EntityPage({ params }: { params: { id: string } }) {
  const entity = await fetchEntity(params.id);
  return <EntityDetail entity={entity} />;
}

Best for:

Entity detail pages
Blog posts
Product listings
Content with predictable update patterns

Server-Side Rendering (SSR)

To use SSR for real-time data:

typescript

// app/dashboard/page.tsx
export const dynamic = 'force-dynamic';

export default async function Dashboard() {
  const data = await fetchUserData();
  return <DashboardView data={data} />;
}

Best for:

User dashboards
Personalized content
Real-time data displays
Authentication-dependent pages

Streaming

To use streaming for progressive loading:

typescript

// app/timeline/page.tsx
import { Suspense } from 'react';

export default function TimelinePage() {
  return (
    <div>
      <TimelineHeader />
      <Suspense fallback={<TimelineLoader />}>
        <TimelineEvents />
      </Suspense>
    </div>
  );
}

Best for:

Pages with slow data fetching
Complex pages with multiple data sources
Improving perceived performance

Consult

references/rendering-strategies.md

for detailed strategy comparison.

Revalidation Configuration

Time-Based Revalidation

To set revalidation intervals:

typescript

// Revalidate every 60 seconds
export const revalidate = 60;

// Revalidate every hour
export const revalidate = 3600;

// Revalidate every day
export const revalidate = 86400;

On-Demand Revalidation

To implement on-demand cache invalidation:

typescript

// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache';
import { NextRequest } from 'next/server';

export async function POST(request: NextRequest) {
  const { path, tag } = await request.json();

  if (path) {
    revalidatePath(path);
  }

  if (tag) {
    revalidateTag(tag);
  }

  return Response.json({ revalidated: true, now: Date.now() });
}

Use from Server Actions:

typescript

'use server';

import { revalidatePath } from 'next/cache';

export async function updateEntity(id: string, data: EntityData) {
  await saveEntity(id, data);
  revalidatePath(`/entities/${id}`);
  revalidatePath('/entities');
}

Cache Tags

To implement cache tag-based revalidation:

typescript

// app/entities/[id]/page.tsx
export default async function EntityPage({ params }: { params: { id: string } }) {
  const entity = await fetch(`/api/entities/${params.id}`, {
    next: {
      tags: [`entity-${params.id}`, 'entities'],
    },
  });

  return <EntityDetail entity={entity} />;
}

Revalidate by tag:

typescript

import { revalidateTag } from 'next/cache';

// Revalidate all pages with 'entities' tag
revalidateTag('entities');

// Revalidate specific entity
revalidateTag(`entity-${entityId}`);

Reference

assets/cache-tag-patterns.ts

for cache tagging patterns.

Route Analysis

Use

scripts/analyze_routes.py

to analyze application routes and recommend strategies:

bash

python scripts/analyze_routes.py ./app

Output includes:

Route path
Recommended rendering strategy
Suggested revalidation interval
Appropriate cache tags
Reasoning for recommendations

Analysis Criteria

Consider these factors:

Data Freshness Requirements
- Real-time: SSR or very short revalidation (1-60s)
- Near real-time: ISR with short interval (60-300s)
- Periodic updates: ISR with medium interval (300-3600s)
- Rarely changes: SSG or long interval (3600s+)
Update Frequency
- Continuous: SSR
- Multiple times per hour: ISR (60-300s)
- Hourly: ISR (3600s)
- Daily: ISR (86400s)
- Weekly+: SSG
Personalization
- User-specific: SSR
- Role-based: SSR or ISR with user context
- Public: SSG or ISR
Data Source Performance
- Fast (<100ms): Any strategy
- Medium (100-500ms): Consider streaming
- Slow (>500ms): Use streaming or aggressive caching

Consult

references/decision-matrix.md

for the complete decision matrix.

Implementation Patterns

Entity Detail Pages

To optimize entity pages:

typescript

// app/entities/[id]/page.tsx
export const revalidate = 1800; // 30 minutes

export async function generateStaticParams() {
  const entities = await fetchAllEntityIds();
  return entities.map((id) => ({ id: id.toString() }));
}

export default async function EntityPage({ params }: { params: { id: string } }) {
  const entity = await fetchEntity(params.id, {
    next: { tags: [`entity-${params.id}`, 'entities'] },
  });

  return <EntityDetail entity={entity} />;
}

List Pages

To optimize listing pages:

typescript

// app/entities/page.tsx
export const revalidate = 300; // 5 minutes

export default async function EntitiesPage({
  searchParams,
}: {
  searchParams: { page?: string };
}) {
  const page = parseInt(searchParams.page || '1');
  const entities = await fetchEntities(page, {
    next: { tags: ['entities'] },
  });

  return <EntityList entities={entities} />;
}

Timeline Pages

To optimize timeline with streaming:

typescript

// app/timeline/page.tsx
import { Suspense } from 'react';

export default function TimelinePage() {
  return (
    <div>
      <Suspense fallback={<TimelineHeaderSkeleton />}>
        <TimelineHeader />
      </Suspense>
      <Suspense fallback={<EventsSkeleton />}>
        <TimelineEvents />
      </Suspense>
    </div>
  );
}

async function TimelineEvents() {
  const events = await fetchTimelineEvents({
    next: { tags: ['timeline'], revalidate: 600 },
  });
  return <EventsList events={events} />;
}

Dashboard Pages

To implement personalized dashboard:

typescript

// app/dashboard/page.tsx
export const dynamic = 'force-dynamic';

export default async function DashboardPage() {
  const session = await getSession();
  const data = await fetchUserDashboard(session.userId);

  return (
    <div>
      <Suspense fallback={<StatsSkeleton />}>
        <DashboardStats userId={session.userId} />
      </Suspense>
      <Suspense fallback={<ActivitySkeleton />}>
        <RecentActivity userId={session.userId} />
      </Suspense>
    </div>
  );
}

Cache Invalidation Strategies

Granular Invalidation

To invalidate specific resources:

typescript

// After entity update
revalidateTag(`entity-${entityId}`);

// After relationship change
revalidateTag(`entity-${sourceId}`);
revalidateTag(`entity-${targetId}`);
revalidateTag('relationships');

Cascade Invalidation

To invalidate related resources:

typescript

async function updateEntity(id: string, data: EntityData) {
  await saveEntity(id, data);

  // Invalidate entity page
  revalidateTag(`entity-${id}`);

  // Invalidate list pages
  revalidateTag('entities');

  // Invalidate related pages
  const relationships = await getEntityRelationships(id);
  for (const rel of relationships) {
    revalidateTag(`entity-${rel.targetId}`);
  }
}

Batch Invalidation

To invalidate multiple resources efficiently:

typescript

async function bulkUpdateEntities(updates: EntityUpdate[]) {
  await saveBulkUpdates(updates);

  // Collect unique tags
  const tags = new Set<string>(['entities']);
  for (const update of updates) {
    tags.add(`entity-${update.id}`);
  }

  // Revalidate all at once
  for (const tag of tags) {
    revalidateTag(tag);
  }
}

Performance Optimization

Stale-While-Revalidate

To implement SWR pattern:

typescript

export const revalidate = 60; // Revalidate every minute
export const dynamic = 'force-static'; // Serve stale while revalidating

Parallel Data Fetching

To fetch data in parallel:

typescript

export default async function EntityPage({ params }: { params: { id: string } }) {
  const [entity, relationships, timeline] = await Promise.all([
    fetchEntity(params.id),
    fetchRelationships(params.id),
    fetchTimeline(params.id),
  ]);

  return <EntityDetailView entity={entity} relationships={relationships} timeline={timeline} />;
}

Selective Streaming

To stream only slow components:

typescript

export default function EntityPage({ params }: { params: { id: string } }) {
  return (
    <div>
      <EntityHeader id={params.id} /> {/* Fast, no streaming */}
      <Suspense fallback={<RelationshipsSkeleton />}>
        <EntityRelationships id={params.id} /> {/* Slow, stream it */}
      </Suspense>
    </div>
  );
}

Monitoring and Testing

To monitor cache performance:

Cache Hit Rates: Track ISR cache hits vs. regenerations
Revalidation Frequency: Monitor how often pages regenerate
Response Times: Measure time to first byte (TTFB)
Stale Serving: Track stale-while-revalidate occurrences

Use Next.js analytics or custom logging:

typescript

// middleware.ts
export function middleware(request: NextRequest) {
  const start = Date.now();

  return NextResponse.next({
    headers: {
      'x-response-time': `${Date.now() - start}ms`,
    },
  });
}

Best Practices

Start Conservative: Begin with shorter revalidation intervals, increase gradually
Use Cache Tags: Prefer tag-based invalidation over path-based
Monitor Performance: Track cache hit rates and response times
Plan Invalidation: Design invalidation strategy with data mutations
Test Edge Cases: Verify behavior with stale data and revalidation
Document Decisions: Record why specific intervals were chosen
Consider Users: Balance freshness with performance

Troubleshooting

Common issues:

Stale Data Persisting: Check cache tag implementation and invalidation logic
Excessive Regeneration: Increase revalidation interval or fix trigger-happy invalidation
Slow Page Loads: Add streaming for slow components
Cache Not Working: Verify fetch options and dynamic/static configuration
Development vs Production: Remember ISR only works in production builds

revalidation-strategy-planner

NPX Install

Tags

SKILL.md Content

Revalidation Strategy Planner

Overview

Rendering Strategies

Static Site Generation (SSG)

Incremental Static Regeneration (ISR)

Server-Side Rendering (SSR)

Streaming

Revalidation Configuration

Time-Based Revalidation

On-Demand Revalidation

Cache Tags

Route Analysis

Analysis Criteria

Implementation Patterns

Entity Detail Pages

List Pages

Timeline Pages

Dashboard Pages

Cache Invalidation Strategies

Granular Invalidation

Cascade Invalidation

Batch Invalidation

Performance Optimization

Stale-While-Revalidate

Parallel Data Fetching

Selective Streaming

Monitoring and Testing

Best Practices

Troubleshooting