Full route cache in NextJS - Deep Dive

Overview - Full route cache

What is it?

Full route cache in Next.js is a way to store the complete output of a page route so that when a user visits that page again, the server can quickly send the saved version without rebuilding it. This means the page loads faster because the server skips repeating the work of generating the page. It works by saving the HTML and data for the entire route after the first request.

Why it matters

Without full route caching, every time someone visits a page, the server must rebuild it from scratch, which can slow down the website and make users wait longer. Full route cache makes websites feel faster and smoother, improving user experience and reducing server load. This is especially important for pages that don’t change often but get many visitors.

Where it fits

Before learning full route cache, you should understand how Next.js routing and server-side rendering work. After mastering full route cache, you can explore incremental static regeneration and edge caching to optimize performance further.

Mental Model

Core Idea

Full route cache saves the entire page output so the server can reuse it instantly for future requests, skipping repeated work.

Think of it like...

Imagine a bakery that bakes a cake only once and then stores it on a shelf. When a customer orders the same cake, the bakery just grabs it from the shelf instead of baking again, serving it faster.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ First Request │──────▶│ Build Page    │──────▶│ Save to Cache │
└───────────────┘       └───────────────┘       └───────────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │ Serve Cached Page│
                          └─────────────────┘
                                   ▲
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Next Requests │──────▶│ Check Cache   │──────▶│ Return Cached  │
└───────────────┘       └───────────────┘       └───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Next.js Routing Basics

Concept: Learn how Next.js handles page routes and serves pages.

Next.js uses a file-based routing system. Each file in the 'pages' folder corresponds to a route URL. When a user visits a URL, Next.js runs code to generate the page content, either on the server or client.

Result

You know how URLs map to page files and how Next.js builds pages dynamically.

Understanding routing is essential because caching works by saving the output of these routes.

2

Foundation

What is Server-Side Rendering (SSR)?

Concept: Learn how Next.js builds pages on the server for each request.

SSR means the server creates the full HTML for a page every time someone visits. This ensures fresh data but can be slow if done repeatedly.

Result

You see why building pages on every request can cause delays.

Knowing SSR helps you appreciate why caching the full page output speeds things up.

3

Intermediate

Introducing Full Route Cache Concept

🤔Before reading on: do you think caching only parts of a page or the whole page is faster? Commit to your answer.

Concept: Full route cache stores the entire page output after the first build to reuse later.

Instead of rebuilding the page every time, Next.js can save the full HTML and data after the first request. Later requests get this saved version instantly.

Result

Pages load faster because the server skips rebuilding and sends the cached page.

Understanding full route cache shows how caching the whole page output can drastically improve speed.

4

Intermediate

How Next.js Implements Full Route Cache

🤔Before reading on: do you think the cache is stored in memory, disk, or both? Commit to your answer.

Concept: Next.js stores cached pages in memory or on disk depending on configuration and serves them directly on requests.

When a page is first requested, Next.js builds it and saves the output in a cache store. Future requests check this cache first and serve the saved page if available.

Result

The server workload reduces, and response times improve for cached pages.

Knowing where and how cache is stored helps you optimize performance and resource use.

5

Intermediate

Cache Invalidation and Updates

🤔Before reading on: do you think cached pages update automatically or need manual refresh? Commit to your answer.

Concept: Cached pages must be refreshed when content changes to avoid showing outdated information.

Next.js can invalidate cache on code or data changes, or after a set time. This ensures users see fresh content while still benefiting from caching.

Result

Users get fast pages that are also up-to-date.

Understanding cache invalidation prevents stale content and keeps user experience smooth.

6

Advanced

Combining Full Route Cache with Incremental Static Regeneration

🤔Before reading on: do you think full route cache and ISR are the same or different? Commit to your answer.

Concept: ISR lets Next.js update static pages in the background while serving cached versions, blending caching and freshness.

With ISR, Next.js serves cached pages immediately but regenerates them after a set time in the background, updating the cache without slowing users.

Result

Pages stay fast and fresh without manual cache clearing.

Knowing how full route cache works with ISR helps build highly performant, scalable apps.

7

Expert

Advanced Cache Strategies and Edge Caching

🤔Before reading on: do you think full route cache alone is enough for global performance? Commit to your answer.

Concept: Full route cache can be combined with edge caching to serve pages from servers close to users worldwide.

Edge caching stores cached pages on servers around the world, reducing latency. Next.js can push cached pages to these edge locations for instant delivery globally.

Result

Users everywhere get fast page loads with minimal delay.

Understanding edge caching with full route cache unlocks global scale and speed.

Under the Hood

When a Next.js route is requested, the server checks if a cached HTML output exists for that route. If not, it runs the page's rendering logic, including data fetching and React rendering, to produce HTML. This HTML is then saved in a cache store keyed by the route path. Subsequent requests retrieve this cached HTML directly, bypassing rendering. Cache invalidation triggers re-rendering and cache update. The cache can be stored in memory, disk, or external stores depending on deployment.

Why designed this way?

Next.js was designed to balance dynamic content freshness with performance. Full route cache reduces server load and latency by reusing work. Alternatives like rebuilding every request were too slow, and pure static generation lacked flexibility. This design allows fast responses while supporting dynamic data and updates.

┌───────────────┐
│ Client       │
└──────┬────────┘
       │ Request /page
       ▼
┌───────────────┐
│ Cache Lookup │
└──────┬────────┘
       │ Cache hit? ──No──▶
       ▼                 │
┌───────────────┐        │
│ Build Page    │        │
│ (Render +    │        │
│ Data Fetch)  │        │
└──────┬────────┘        │
       │ Save to Cache   │
       ▼                 │
┌───────────────┐        │
│ Serve Page    │◀───────┘
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does full route cache mean pages never update unless you restart the server? Commit to yes or no.

Common Belief: Once a page is cached, it never changes until the server restarts.

Reality: Next.js supports cache invalidation and regeneration to update cached pages without server restarts.

Why it matters: Believing this causes developers to avoid caching or manually restart servers, wasting time and resources.

Quick: Is full route cache the same as client-side caching? Commit to yes or no.

Common Belief: Full route cache stores data on the user's browser like client cache.

Reality: Full route cache stores the entire page on the server side, not on the client browser.

Why it matters: Confusing these leads to wrong debugging and performance expectations.

Quick: Does caching only speed up static pages, not dynamic ones? Commit to yes or no.

Common Belief: Full route cache only works for static pages without dynamic data.

Reality: Full route cache can speed up dynamic pages by caching rendered output and updating it when data changes.

Why it matters: This misconception limits use of caching and misses performance gains on dynamic content.

Quick: Does full route cache always reduce server memory usage? Commit to yes or no.

Common Belief: Caching pages always lowers server memory use.

Reality: Caching can increase memory use because cached pages consume storage, trading memory for speed.

Why it matters: Ignoring this can cause unexpected resource exhaustion in production.

Expert Zone

1

Full route cache effectiveness depends heavily on cache key design; subtle differences in URLs or query parameters can cause cache misses.

2

Cache invalidation strategies must balance freshness and performance; aggressive invalidation reduces cache benefits, while lax invalidation risks stale content.

3

Combining full route cache with middleware or authentication requires careful handling to avoid caching sensitive or user-specific data.

When NOT to use

Full route cache is not ideal for highly personalized pages that change per user or request. Instead, use client-side rendering or server-side rendering without caching. Also, for very frequently changing data, consider real-time data fetching or streaming approaches.

Production Patterns

In production, teams often use full route cache with incremental static regeneration to serve mostly static content quickly while updating pages in the background. They also integrate edge caching via CDNs to deliver cached pages globally with minimal latency.

Connections

Content Delivery Networks (CDNs)

Full route cache output is often stored and served by CDNs at the edge.

Understanding full route cache helps grasp how CDNs speed up content delivery by caching full pages close to users.

Memoization in Programming

Both cache results of expensive operations to avoid repeating work.

Knowing memoization clarifies the principle behind caching full page outputs to improve performance.

Library Book Lending Systems

Caching is like lending a book multiple times without rewriting it each time.

Recognizing this connection helps appreciate caching as a resource-saving sharing mechanism.

Common Pitfalls

#1 Serving stale pages because cache is never refreshed.

Wrong approach:

const cache = new Map();

export async function handler(req, res) {
if (cache.has(req.url)) {
res.send(cache.get(req.url));
return;
}
const page = await buildPage(req.url);
cache.set(req.url, page);
res.send(page);
// No cache invalidation logic
}

Correct approach:

const cache = new Map();
const CACHE_TTL = 60000; // 1 minute
const cacheTimes = new Map();

export async function handler(req, res) {
const now = Date.now();
if (cache.has(req.url) && (now - cacheTimes.get(req.url) < CACHE_TTL)) {
res.send(cache.get(req.url));
return;
}
const page = await buildPage(req.url);
cache.set(req.url, page);
cacheTimes.set(req.url, now);
res.send(page);
}

Root cause:

Not implementing cache expiration or invalidation causes outdated content to be served indefinitely.

#2 Caching user-specific pages and exposing private data.

Wrong approach:

export async function handler(req, res) {
if (cache.has(req.url)) {
res.send(cache.get(req.url));
return;
}
const page = await buildUserPage(req.user);
cache.set(req.url, page);
res.send(page);
}

Correct approach:

export async function handler(req, res) {
if (req.user) {
const page = await buildUserPage(req.user);
res.send(page); // No caching for user-specific pages
return;
}
if (cache.has(req.url)) {
res.send(cache.get(req.url));
return;
}
const page = await buildPage(req.url);
cache.set(req.url, page);
res.send(page);
}

Root cause:

Failing to separate public and private content leads to caching sensitive user data.

#3 Assuming full route cache replaces client-side caching.

Wrong approach:

// Server caches full page, but client always refetches
fetch('/page').then(res => res.text()).then(html => {
document.body.innerHTML = html;
// No client cache or service worker
});

Correct approach:

// Use service workers or HTTP cache headers for client caching
// Server caches full page for fast response
// Client caches resources to avoid refetching

Root cause:

Confusing server-side full route cache with client-side caching mechanisms.

Key Takeaways

Full route cache stores the entire rendered page on the server to serve future requests instantly.

It improves website speed and reduces server work by avoiding repeated page builds.

Cache invalidation is crucial to keep content fresh and avoid showing outdated pages.

Combining full route cache with incremental static regeneration and edge caching creates fast, scalable web apps.

Understanding caching limits helps avoid mistakes like caching private data or stale content.