nextjs-static-shells

name	nextjs-static-shells
displayName	Next.js Static Shells
description	Static-first Next.js 16 architecture patterns: cached shells with dynamic slots, provider islands, 'use cache' boundaries, and link preloading strategy. Use when building or refactoring Next.js routes to maximize static rendering, implementing 'use cache' with dynamic personalization, splitting entry vs static renderers, scoping client providers, or tuning prefetch behavior. Triggers on 'static shell', 'use cache pattern', 'dynamic slots', 'provider island', 'prefetch strategy', 'static first', 'cache boundary', 'route goes dynamic unexpectedly', or any Next.js architecture work involving mixed static/dynamic rendering.
version	1.0.0
author	Joel Hooks
tags	["nextjs","architecture","caching","performance","rsc","static"]
disable-model-invocation	true

Static-First Next.js 16 Patterns

Build a static shell first, then cut small dynamic holes where personalization or request-specific behavior is required.

• Static shell = deterministic, cacheable, fast first paint
• Dynamic holes = isolated request/user behavior streamed with Suspense
• Client interactivity = provider islands, not global client sprawl

---

Route Architecture: Entry + Static + Slots

Pattern

1. Entry component (server, request-aware)
   • Reads params/search/auth/session/cookies
   • Validates access, resolves IDs, prepares dynamic props
2. Static renderer (server, 'use cache')
   • Renders deterministic layout/content
   • Accepts dynamic UI as slot props (ReactNode)
3. Dynamic slots
   • Injected from entry component
   • Suspense-wrapped where rendered in static shell

Why This Works

• Static shell stays cacheable
• Dynamic behavior is explicit and narrow
• Streaming keeps UI responsive
• No accidental full-route dynamic bailout

import { Suspense, type ReactNode } from 'react';

type PageProps = { params: Promise<{ slug: string }> };

/** Request-aware server entry. */
export default async function PageEntry({ params }: PageProps) {
  const { slug } = await params;

  const staticData = await getStaticData(slug); 
   userData =  (); 

   dynamicPanel = ;

   ;
}

  = {
  : ;
  ?: ;
};


  () {
  ;

   (
    
  );
}