Core Mechanics of Partial Prerendering
Partial Prerendering (PPR) in Next.js 15 leverages the App Router and React Server Components to prerender static portions of a page while leaving dynamic segments as holes. During the build or revalidation phase, Next.js generates a static HTML shell that includes fallback content defined inside React Suspense boundaries. When a client requests the page, the static shell is served immediately from the edge cache or CDN. The dynamic components inside each Suspense boundary execute on the server at request time and stream their content into the pre-allocated holes.
This approach solves the traditional dichotomy between static site generation (SSG) and server-side rendering (SSR). Full SSG cannot incorporate per-request data such as user sessions or real-time inventory. Full SSR forces the entire page to wait for the slowest data fetch before any HTML reaches the client. PPR gives developers granular control: mark only the parts that truly need to be dynamic while keeping layout, navigation, marketing copy, and non-personalized UI fully static.
React 18.2+ and Next.js 15.0.0+ are required. The feature became stable in Next.js 15 after multiple experimental iterations in the 14.x series. The magic happens at the intersection of the React compiler's static analysis, the Next.js route segment cache, and the streaming capabilities of the Node.js or Edge runtime.
Enabling Partial Prerendering in a Project
Create a new Next.js 15 application with the command npx create-next-app@15 my-ppr-app --typescript --tailwind --eslint --app. In next.config.mjs enable PPR explicitly even though many routes opt in automatically when Suspense boundaries are present:
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
experimental: {
ppr: true,
},
};
export default nextConfig;
After enabling the flag, any route that uses async Server Components combined with Suspense will trigger partial prerendering. Next.js analyzes the component tree during build and separates static and dynamic segments. Static segments are written to .next/static and can be served by Vercel Edge Network or any CDN that respects the cache headers Next.js emits.
Route-level configuration remains available. You can force a route to be fully dynamic with the export const dynamic = 'force-dynamic'; constant, but doing so disables the static shell for that entire route. The recommended pattern is to keep the default (which respects fetch cache options) and wrap only the dynamic subtrees.
Creating Static Shells with Suspense Boundaries
The primary API for defining holes is the Suspense component from React. Everything outside a Suspense boundary is prerendered to static HTML. Everything inside becomes a dynamic island that executes at request time.
import { Suspense } from 'react';
async function UserGreeting({ userId }: { userId: string }) {
const user = await fetch(`https://api.example.com/users/${userId}`, {
cache: 'no-store',
}).then(res => res.json());
return (
<div className="greeting">
Welcome back, {user.name}
</div>
);
}
export default function DashboardPage() {
return (
<main>
<header className="static-header">
<nav>...static navigation that never changes...</nav>
<h1>Dashboard</h1>
</header>
<Suspense fallback={<Skeleton />}>
<UserGreeting userId="current-user" />
</Suspense>
<section className="static-marketing">
Static promotional content that is prerendered and cached.
</section>
</main>
);
}
In the example above, the header and marketing section are emitted as static HTML during the build. The UserGreeting component is replaced with the fallback Skeleton in the initial static payload. When the request arrives, Next.js renders only the dynamic component and replaces the fallback via streaming or a single flush depending on the runtime.
Multiple independent Suspense boundaries can coexist on the same page. Next.js will fill each hole as soon as its data is ready, enabling progressive rendering even among dynamic sections.
Data Fetching Rules Inside PPR Routes
Inside a dynamic component wrapped by Suspense, the default fetch behavior changes. Calls without explicit cache options default to no-store when the route segment is considered dynamic. To opt into caching for a particular dynamic island, use the next: { revalidate: 60 } option introduced in the App Router.
const data = await fetch('/api/stats', {
next: {
revalidate: 30, // seconds
tags: ['dashboard-stats'],
},
});
You can also use the revalidateTag and revalidatePath functions from next/cache to purge specific dynamic holes without rebuilding the entire static shell. This is especially useful for SaaS dashboards where a user action (such as updating a project) should refresh only the affected dynamic panel.
Database ORMs such as Drizzle ORM 0.29+ or Prisma 5.12+ work naturally inside these async Server Components. Because the component executes only on the server, you can safely use connection pooling with @neondatabase/serverless or postgres.js without exposing credentials to the client.
Authentication Patterns Compatible with PPR
Authentication is inherently dynamic. Reading cookies or headers forces the route segment to be dynamic, yet PPR still delivers the surrounding static shell instantly. The following pattern is common in production:
import { cookies } from 'next/headers';
import { Suspense } from 'react';
async function AuthenticatedContent() {
const cookieStore = cookies();
const sessionToken = cookieStore.get('auth-token')?.value;
if (!sessionToken) {
return <LoginPrompt />;
}
const user = await getUserFromToken(sessionToken);
return <DashboardShell user={user} />;
}
export default function Page() {
return (
<Suspense fallback={<PublicStaticShell />}>
<AuthenticatedContent />
</Suspense>
);
}
The static shell can include a public navigation bar, hero section, or marketing footer that is identical for both logged-in and logged-out users. Only the personalized area becomes dynamic. This pattern improves perceived performance dramatically because the majority of the DOM is painted before the authentication lookup completes.
When using libraries such as Lucia Auth 3.x or Clerk 5.x, place the session verification inside the innermost dynamic component rather than at the top-level page. This preserves the largest possible static shell.
Nested Boundaries and Progressive Enhancement
Complex pages benefit from multiple nested or sibling Suspense boundaries with different fallbacks. A typical SaaS analytics dashboard might have four independent dynamic sections: usage metrics, recent activity, billing summary, and AI recommendations. Each can show its own skeleton while the others load independently.
Order of rendering is non-deterministic and depends on data fetch latency. To give users a predictable experience, design skeletons that maintain layout using CSS grid or flexbox with fixed aspect ratios. Avoid cumulative layout shift (CLS) scores above 0.05 by reserving exact space for each dynamic island.
Streaming is automatic. Next.js emits the static shell first, then sends React Server Component (RSC) payload chunks as each Suspense boundary resolves. On the client, React 19's use hook or the built-in hydration logic replaces the fallback with real content without a full page reload.
Caching, Revalidation, and On-Demand Purge
The static shell respects the same cache rules as traditional static routes. Use export const revalidate = 3600; at the route level to set a default revalidation time for the shell itself. Dynamic islands ignore this constant and follow their own next.revalidate settings.
For on-demand revalidation after a user mutates data, call revalidatePath('/dashboard', 'page') or revalidateTag('user-stats') from a Server Action. This regenerates the static shell in the background while leaving currently executing dynamic requests unaffected. In production deployments on Vercel, this operation typically completes in under 800 ms for medium-complexity pages.
Monitor cache hit rates using the Vercel Analytics dashboard or self-hosted OpenTelemetry instrumentation on the next/server layer. A healthy PPR route should show >85% static shell cache hits for non-personalized traffic.
Debugging and Observability Techniques
Enable detailed logging with NEXT_DEBUG=1 environment variable during local development. You will see console messages indicating which segments were prerendered statically and which were left as dynamic holes. The next build output also prints a summary table showing static vs dynamic bytes per route.
For production observability, instrument the dynamic components with OpenTelemetry traces. Wrap data fetches with trace.getTracer('ppr-dynamic').startSpan('fetch-user-data'). This lets you correlate slow dynamic islands with specific user sessions or database queries.
Common pitfalls include accidentally calling headers() or cookies() in a component intended to be static. Next.js will warn at build time when it detects such usage inside a statically analyzable segment. Move those calls into a dedicated dynamic wrapper component.
Use the React Developer Tools Profiler to measure hydration time of the dynamic islands. Target under 80 ms for the client-side React work after the RSC payload arrives.
Performance Trade-offs and Production Considerations
PPR delivers measurable improvements in Time to First Byte (TTFB) because the static shell can be cached at the edge and served in single-digit milliseconds. However, the dynamic islands still require server compute on every request. If your dynamic components perform heavy SQL joins or call external APIs with high latency, you may see increased origin server load compared to fully static pages.
Memory usage on the server increases slightly because the static shell and dynamic execution share the same request context in the Node.js runtime. In tests with 500 concurrent users on a 2 vCPU instance, PPR routes consumed approximately 18% more memory than equivalent static routes but 42% less than fully dynamic SSR routes that blocked on all data.
Edge runtime compatibility is partial. Dynamic islands that rely on Node.js-only APIs such as fs or certain ORMs cannot run at the edge. For those cases, keep the dynamic component on the Node.js runtime while still benefiting from the static shell delivered from Edge.
Bundle size impact is minimal. The static shell contains no JavaScript for the prerendered parts. Only the dynamic islands and their client-side interactivity add to the client bundle. This often results in First Contentful Paint (FCP) under 900 ms on 3G networks when combined with good skeleton design.
Real-World Implementation Example: SaaS Billing Dashboard
Consider a SaaS billing dashboard. The page contains a static sidebar navigation, a header with company logo, and three dynamic sections: current usage meters, invoice history, and plan upgrade prompts based on usage thresholds.
The static shell includes the sidebar and header. Each of the three sections is wrapped in its own Suspense boundary with tailored skeletons that match the final layout dimensions. The usage meters fetch from a Redis cache via Upstash, the invoice history queries PostgreSQL through Drizzle ORM 0.29, and the upgrade prompt runs a simple rule engine on the server.
Because the three sections are independent, a slow database query for invoices does not delay the usage meters. Users see their usage numbers almost instantly while the invoice table populates moments later. After a plan change, calling revalidateTag('billing-data') from a Server Action updates all three islands without regenerating the entire static navigation shell.
This pattern has been used successfully in production applications serving thousands of daily active users. The static shell reduces CDN egress costs because the majority of HTML bytes are served from cache. Dynamic islands are typically under 6 KB each when compressed.
Limitations and Decision Framework
PPR is not suitable for every route. Pages that are 95% dynamic, such as a real-time collaborative editor, gain little benefit and add mental overhead. Routes that must execute entirely within the Edge runtime today still require the runtime = 'edge' directive, which disables static shell generation.
Complex component trees with many nested Server Components can make it difficult to predict exactly which parts will be static. The current debugging tools help, but teams new to the App Router often need one or two iterations to achieve optimal shell-to-dynamic ratios.
Use the following decision matrix: If more than 60% of the rendered HTML can be static and the dynamic parts can tolerate independent loading states, adopt PPR. If the page must render identically for every user with no personalization, prefer static rendering with ISR. If every pixel depends on per-request data with strict ordering requirements, full dynamic SSR remains the correct choice.
Incremental adoption is straightforward. You can convert individual pages without changing the rest of the application. Start with high-traffic marketing pages that have small dynamic sections such as "Featured customers" or "Live pricing calculator" to gain immediate performance wins.
Monitor Core Web Vitals in the field. Pages using well-designed PPR consistently show 15-30 point improvements in LCP and INP scores compared to equivalent SSR implementations, provided fallback skeletons are lightweight and do not contain heavy client-side JavaScript.
