nextjs-static-shells

# 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 ```tsx 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); // deterministic const userData = await getUserData(); // request-dependent const dynamicPanel = <PersonalizedPanel userData={userData} />; return <PageStatic data={staticData} panel={dynamicPanel} />; } type PageStaticProps = { data: StaticData; panel?: ReactNode; }; /** Cached static shell. Keep request-volatile reads out. */ async function PageStatic({ data, panel }: PageStaticProps) { 'use cache'; return ( <main> <Hero data={data.hero} /> <Content data={data.content} /> <Suspense fallback={<PanelSkeleton />}>{panel}</Suspense> </main> ); } ``` --- ## Cache Components Setup & Mechanics ### Enable ```ts // next.config.ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { cacheComponents: true, } export default nextConfig ``` Replaces the old `experimental.ppr` flag. ### Three Content Types | Type | Characteristic | Example | |------|---------------|---------| | **Static** | Synchronous, pure computation | `<header><h1>Our Blog</h1></header>` | | **Cached** (`'use cache'`) | Async but deterministic for given inputs | `db.posts.findMany()` with `cacheLife('hours')` | | **Dynamic** (Suspense) | Runtime/request-specific, must be fresh | `cookies()`, user session, notifications | ### `'use cache'` Scope Levels ```tsx // File level — entire module cached 'use cache' export default async function Page() { /* ... */ } // Component level export async function CachedComponent() { 'use cache' const data = await fetchData() return <div>{data}</div> } // Function level export async function getData() { 'use cache' return db.query('SELECT * FROM posts') } ``` ### Cache Profiles with `cacheLife()` ```tsx import { cacheLife } from 'next/cache' async function getData() { 'use cache' cacheLife('hours') // Built-in: 'default' | 'minutes' | 'hours' | 'days' | 'weeks' | 'max' return fetch('/api/data') } // Or inline config: async function getDataCustom() { 'use cache' cacheLife({ stale: 3600, // 1h — serve stale while revalidating revalidate: 7200, // 2h — background revalidation interval expire: 86400, // 1d — hard expiration }) return fetch('/api/data') } ``` Built-in profile shortcuts: `'use cache'` alone → 5m stale / 15m revalidate. `'use cache: remote'` → platform KV. `'use cache: private'` → allows runtime APIs (compliance escape hatch). ### Cache Invalidation ```tsx import { cacheTag } from 'next/cache' async function getProduct(id: string) { 'use cache' cacheTag('products', `product-${id}`) return db.products.findUnique({ where: { id } }) } ``` **`updateTag()`** — immediate, same-request invalidation: ```tsx 'use server' import { updateTag } from 'next/cache' export async function updateProduct(id: string, data: FormData) { await db.products.update({ where: { id }, data }) updateTag(`product-${id}`) // caller sees fresh data } ``` **`revalidateTag()`** — background stale-while-revalidate: ```tsx 'use server' import { revalidateTag } from 'next/cache' export async function createPost(data: FormData) { await db.posts.create({ data }) revalidateTag('posts') // next request sees fresh data } ``` ### Cache Key Generation (Automatic) Keys derived from: build ID + function location hash + serializable arguments + closure variables. No manual `keyParts` like `unstable_cache`. ```tsx async function Component({ userId }: { userId: string }) { const getData = async (filter: string) => { 'use cache' // cache key = userId (closure) + filter (argument) return fetch(`/api/users/${userId}?filter=${filter}`) } return getData('active') } ``` --- ## What Cannot Live Inside `'use cache'` **Hard rule:** No per-request volatility inside cached boundaries. | Banned inside `'use cache'` | Why | |---|---| | `cookies()`, `headers()` | Request-specific | | `searchParams` | Request-specific | | Session/auth reads | User-specific | | Hidden user logic in helper calls | Invisible request dependency | | Side effects tied to request lifecycle | Non-deterministic | | `Math.random()`, `Date.now()` | Execute once at build time inside cache | ### Fix: Extract Outside, Pass as Arguments ```tsx // Wrong — runtime API inside 'use cache' async function CachedProfile() { 'use cache' const session = (await cookies()).get('session')?.value // Error! return <div>{session}</div> } // Correct — extract in entry, pass as prop async function ProfilePage() { const session = (await cookies()).get('session')?.value return <CachedProfile sessionId={session} /> } async function CachedProfile({ sessionId }: { sessionId: string }) { 'use cache' // sessionId becomes part of cache key automatically const data = await fetchUserData(sessionId) return <div>{data.name}</div> } ``` Exception: `'use cache: private'` allows `cookies()` / `headers()` for compliance cases where refactoring is impractical. --- ## RSC Boundary Rules These interact directly with the static shell pattern. ### Async Client Components Are Invalid Client components **cannot** be async. Only Server Components can be async. ```tsx // Bad 'use client' export default async function UserProfile() { const user = await getUser() // Cannot await in client return <div>{user.name}</div> } // Good — fetch in server entry, pass data down // page.tsx (server) export default async function Page() { const user = await getUser() return <UserProfile user={user} /> } // UserProfile.tsx (client) 'use client' export function UserProfile({ user }: { user: User }) { return <div>{user.name}</div> } ``` ### Non-Serializable Props Kill the Boundary Props from Server → Client must be JSON-serializable. | Cannot pass | Fix | |---|---| | Functions (except Server Actions) | Define inside client component | | `Date` objects | `.toISOString()` on server | | `Map`, `Set` | `Object.fromEntries()` / `Array.from()` | | Class instances | Pass plain object | Server Actions (`'use server'`) **can** be passed to client components — they're the exception. --- ## Async Patterns (Next.js 15+) `params`, `searchParams`, `cookies()`, `headers()` are all async. Type them as `Promise<...>` and `await` in the entry component. ```tsx type PageProps = { params: Promise<{ slug: string }> searchParams: Promise<{ query?: string }> } export default async function Page({ params, searchParams }: PageProps) { const { slug } = await params const { query } = await searchParams // ... } ``` For synchronous client components that need params, use `React.use()`: ```tsx import { use } from 'react' export default function Page({ params }: { params: Promise<{ slug: string }> }) { const { slug } = use(params) } ``` --- ## Suspense Boundary Requirements ### `useSearchParams` Always Needs Suspense Without Suspense, the entire page becomes CSR: ```tsx // Bad — entire page CSR bailout 'use client' import { useSearchParams } from 'next/navigation' export default function SearchBar() { const searchParams = useSearchParams() return <div>Query: {searchParams.get('q')}</div> } // Good — isolated in Suspense import { Suspense } from 'react' export default function Page() { return ( <Suspense fallback={<SearchSkeleton />}> <SearchBar /> </Suspense> ) } ``` ### Quick Reference | Hook | Suspense Required | |------|-------------------| | `useSearchParams()` | Always | | `usePathname()` | Yes in dynamic routes | | `useParams()` | No | | `useRouter()` | No | --- ## Provider Islands (Client Providers Done Cleanly) ### Rule Mount client providers **as low as possible** and only where interactivity is needed. - Good: feature-level provider island - Bad: global root provider for local feature state ### Pattern Server entry passes typed initial state. Client provider resolves inside `'use client'` boundary. Hooks stay inside island. ```tsx 'use client'; import { createContext, useContext, useMemo } from 'react'; type FeatureState = { enabled: boolean }; type FeatureContextValue = { state: FeatureState }; const FeatureContext = createContext<FeatureContextValue | null>(null); export function FeatureProvider({ children, initialState, }: { children: React.ReactNode; initialState: FeatureState; }) { const value = useMemo(() => ({ state: initialState }), [initialState]); return <FeatureContext.Provider value={value}>{children}</FeatureContext.Provider>; } export function useFeature() { const ctx = useContext(FeatureContext); if (!ctx) throw new Error('useFeature must be used within FeatureProvider'); return ctx; } ``` --- ## Data Fetching in the Static Shell Model ### Decision Tree | Need | Pattern | |------|---------| | Read data in server component | Fetch directly — no API layer | | Mutation from UI | Server Action (`'use server'`) | | External API / webhook / mobile client | Route Handler | | Client component needs data | Pass from server parent (preferred) or Route Handler | ### Avoiding Waterfalls ```tsx // Bad — sequential const user = await getUser(); const posts = await getPosts(); // Good — parallel const [user, posts] = await Promise.all([getUser(), getPosts()]); // Better — streaming with Suspense (each section independent) <Suspense fallback={<UserSkeleton />}><UserSection /></Suspense> <Suspense fallback={<PostsSkeleton />}><PostsSection /></Suspense> ``` ### Preload Pattern ```tsx import { cache } from 'react';