martelotte.com
← Back to blog

Nginx as an Edge Cache for Nuxt 3 ISR: Revalidating Content at Scale

nuxtvuejavascriptwebdevfrontend

In the ever-accelerating world of web development, user expectations for blazing-fast experiences are higher than ever. As we look towards 2026, building performant, scalable, and resilient web applications is not just a best practice – it’s a necessity. Nuxt 3, with its sophisticated rendering strategies, particularly Incremental Static Regeneration (ISR), has been a game-changer. But what happens when you need to push its capabilities to the absolute limit, serving millions of requests while ensuring content is always fresh?

Enter Nginx as an edge cache. While Nuxt 3’s built-in ISR is incredibly powerful, layering an Nginx cache in front of your Nuxt server can unlock unparalleled performance, significantly reduce server load, and provide robust content revalidation at a scale that traditional setups struggle to match.

The Nuxt 3 ISR Advantage (and Where Nginx Steps In)

Nuxt 3’s ISR is a developer’s dream. It combines the performance benefits of static sites with the flexibility of dynamic content. When you deploy a Nuxt app with ISR enabled (which is often the default behavior for server routes and pages with appropriate Cache-Control headers), Nuxt will:

  1. Serve Stale, Revalidate in Background: For a cached page, Nuxt immediately serves the stale version to the user. In parallel, it triggers a background regeneration of that page. Once regenerated, the new version replaces the old in Nuxt’s internal cache, ready for the next request. This is primarily powered by the stale-while-revalidate HTTP header.
  2. On-Demand Regeneration: For content that changes frequently, you can specify a short s-maxage or even rely on webhook-triggered revalidation.

This approach dramatically improves perceived performance and reduces initial server load compared to pure SSR. However, even with ISR, challenges can arise at extreme scale:

  • Initial Freshness Delay: While stale-while-revalidate is great for perceived speed, there’s still a window where users might see outdated content until Nuxt finishes revalidating in the background. If content changes frequently, this can be an issue.
  • Origin Server Load: Even background revalidations hit your Nuxt server. At massive scale, if many pages become stale simultaneously (e.g., a site-wide update), your Nuxt server can still get overwhelmed by regeneration requests.
  • Network Latency: Even with a fast Nuxt server, the physical distance between your users and your origin server can introduce latency.
  • Immediate Invalidations: For critical content updates (e.g., breaking news, price changes), waiting for stale-while-revalidate might not be acceptable. You need an “instant purge” mechanism.

This is where Nginx, positioned as a reverse proxy and powerful edge cache, becomes an indispensable companion to your Nuxt 3 ISR setup. It acts as the first line of defense, intercepting requests and serving cached content before your Nuxt server even sees them.

Architecting for Scale: Nginx as Your Edge Cache

The goal is to have Nginx sit in front of your Nuxt server, caching responses based on the Cache-Control headers Nuxt provides. When Nginx has a valid cached response, it serves it directly, offloading your Nuxt server entirely. For revalidation, Nginx needs to intelligently respect Nuxt’s stale-while-revalidate directives and, crucially, allow for immediate, targeted cache purges.

Nuxt 3: Preparing for Caching

Nuxt 3, especially with its latest versions (e.g., Nuxt 3.12+ in 2026), leverages h3 and fetch to emit standard HTTP headers. For ISR, the key is the Cache-Control header.

Let’s say you have a dynamic page or an API endpoint that you want to cache. You’d set the Cache-Control header like this:

// server/routes/products/[id].ts
import { defineEventHandler } from 'h3';

export default defineEventHandler(async (event) => {
  const productId = event.context.params?.id;

  // Simulate fetching data from a database/API
  const product = await new Promise(resolve => {
    setTimeout(() => {
      resolve({
        id: productId,
        name: `Product ${productId} - Updated at ${new Date().toLocaleTimeString()}`,
        price: Math.random() * 100,
        description: `This is product number ${productId}.`,
      });
    }, 100);
  });

  // Set Cache-Control header for ISR
  // s-maxage=60: cache for 60 seconds at shared caches (Nginx)
  // stale-while-revalidate=300: Nginx can serve stale for up to 300s while it revalidates in background
  setHeader(event, 'Cache-Control', 'public, s-maxage=60, stale-while-revalidate=300');

  return { product };
});

Here, s-maxage=60 tells Nginx to consider the cache fresh for 60 seconds. After 60 seconds, if Nginx receives a request, it will serve the stale version (if available) and simultaneously initiate a request to your Nuxt server to revalidate the content. This background revalidation can continue for up to 300 seconds (stale-while-revalidate=300).

Nginx: The Caching Powerhouse

Now, let’s configure Nginx to respect these headers and act as our robust edge cache.

# /etc/nginx/nginx.conf or a dedicated site configuration file

# Define a cache zone
# proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=nuxt_cache:100m inactive=60m max_size=10g;
#
# Explanation:
# - /var/cache/nginx: Path to store cache files. Ensure Nginx user has write permissions.
# - levels=1:2: Defines a two-level directory hierarchy for cache storage. Improves performance.
# - keys_zone=nuxt_cache:100m: Creates a shared memory zone named 'nuxt_cache' of 100MB
#   to store cache keys and metadata. Crucial for efficient lookups.
# - inactive=60m: Cached items that haven't been accessed for 60 minutes will be removed.
# - max_size=10g: Maximum size of the cache. When exceeded, Nginx purges least recently used items.

http {
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=nuxt_cache:100m inactive=60m max_size=10g;

    server {
        listen 80;
        server_name yourdomain.com;

        # Optional: Listen on 443 for HTTPS (recommended in 2026!)
        # listen 443 ssl;
        # ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
        # ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

        # Allow specific IP addresses to trigger PURGE requests
        # This is for security of the cache invalidation endpoint
        # For example, your CMS webhook server IP or your internal deployment pipeline IP
        set $purge_allowed "0";
        if ($remote_addr ~ "^(127.0.0.1|YOUR_CMS_IP|YOUR_DEPLOYMENT_IP)$") {
            set $purge_allowed "1";
        }

        location / {
            # Enable proxy caching for this location
            proxy_cache nuxt_cache;

            # Key for cache storage. Important for unique content identification.
            # Includes scheme (http/https), method (GET), host, and full request URI.
            proxy_cache_key "$scheme$request_method$host$request_uri";

            # Respect Cache-Control headers from the backend
            proxy_cache_revalidate on;

            # Allow Nginx to serve stale content while revalidating
            # This directly leverages Nuxt's stale-while-revalidate header
            proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;

            # Add header to debug cache status
            add_header X-Cache-Status $upstream_cache_status;

            # Pass requests to your Nuxt 3 server (e.g., running on port 3000)
            proxy_pass http://localhost:3000;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        # Nginx Cache Purge Endpoint (requires ngx_cache_purge module)
        # This location handles PURGE requests to immediately invalidate cache for a path
        location ~ /purge(/.*) {
            # Only allow authorized IPs to purge the cache
            if ($purge_allowed = "0") {
                return 403; # Forbidden
            }

            # If PURGE method is used, purge the cache for the requested URI
            # $1 captures the path after /purge/
            proxy_cache_purge nuxt_cache "$scheme$request_method$host$1";
            return 204; # No Content, successful purge
        }
    }
}

Key Nginx Directives Explained:

  • proxy_cache_path: Defines the parameters for the cache storage. Crucial for setup.
  • proxy_cache nuxt_cache: Activates the named cache zone for this location.
  • proxy_cache_key: Defines what makes a cached item unique. Using $scheme$request_method$host$request_uri is robust.
  • proxy_cache_revalidate on: Tells Nginx to check the origin server with a If-Modified-Since or If-None-Match header when a cached item is stale, respecting Nuxt’s Cache-Control.
  • proxy_cache_use_stale: Allows Nginx to serve stale content in specific error scenarios (e.g., upstream timeout, 5xx errors) and when updating (i.e., when Nuxt is regenerating the content due to stale-while-revalidate).
  • add_header X-Cache-Status $upstream_cache_status: Invaluable for debugging. You’ll see HIT, MISS, EXPIRED, STALE, etc., in your response headers.
  • location ~ /purge(/.*): This is the magic for immediate revalidation. It requires the ngx_cache_purge module (often available in pre-compiled Nginx versions or requiring a custom build). When a PURGE request hits this endpoint (e.g., PURGE /purge/your-page), Nginx immediately removes the cached item for /your-page, forcing a fresh fetch on the next GET request.

Nuxt 3: Triggering Immediate Purge from Your CMS

To integrate the immediate Nginx purge, you’ll typically set up a Nuxt server route that acts as a secure webhook endpoint. Your CMS (e.g., Strapi, Sanity, DatoCMS, etc.) would call this endpoint whenever content is published or updated, providing the path(s) to be purged.

// server/api/revalidate.ts
import { defineEventHandler, readBody, createError, $fetch } from 'h3';

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(); // Access runtime configuration from nuxt.config.ts
  const { path, secret } = await readBody(event);

  // 1. Secure this endpoint! Validate the secret token.
  if (!secret || secret !== config.revalidationSecret) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Unauthorized: Invalid revalidation secret',
    });
  }

  // 2. Validate the path
  if (!path) {
    throw createError({
      statusCode: 400,
      statusMessage: 'Bad Request: Missing path to revalidate',
    });
  }

  // Ensure path starts with a slash for Nginx purge
  const purgePath = path.startsWith('/') ? path : `/${path}`;

  try {
    // 3. Send a PURGE request to Nginx
    // The Nuxt server should be able to reach your Nginx purge endpoint.
    // Replace `http://localhost:80` with your Nginx's public or internal IP/hostname and port.
    // The Nginx 'purge' location often expects the path to be relative to the root.
    const nginxPurgeUrl = `${config.public.nginxPurgeBaseUrl}/purge${purgePath}`;

    const response = await $fetch(nginxPurgeUrl, {
      method: 'PURGE',
      headers: {
        // If your Nginx purge endpoint requires a specific header for security
        // 'X-Purge-Key': config.nginxPurgeKey,
      },
      // Do not throw on 2xx responses for fetch, Nginx purge returns 204
      // Use parseResponse: false if ngx_cache_purge returns no body and $fetch expects JSON
    });

    console.log(`Nginx cache purge initiated for: ${purgePath}. Status: ${response.status}`);

    return {
      status: 'success',
      message: `Nginx cache for ${purgePath} purged successfully.`,
    };
  } catch (error: any) {
    console.error(`Failed to purge Nginx cache for ${purgePath}:`, error.message);
    throw createError({
      statusCode: 500,
      statusMessage: `Failed to purge Nginx cache: ${error.message}`,
      data: error,
    });
  }
});

And your nuxt.config.ts for runtime configuration:

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Private runtime config for server-side only
    revalidationSecret: process.env.REVALIDATION_SECRET, // CMS sends this
    // Public runtime config available client-side (though this endpoint is server-only)
    public: {
      nginxPurgeBaseUrl: process.env.NINX_PUBLIC_URL || 'http://localhost', // Your Nginx's publicly accessible URL
    },
  },
  // ... other Nuxt configurations
});

Security is paramount! The revalidationSecret must be a strong, randomly generated string, securely stored as an environment variable, and never exposed client-side. Only your trusted CMS or deployment system should have access to this secret and call this endpoint.

Gotchas and Best Practices

  • Install ngx_cache_purge: Confirm your Nginx installation includes the ngx_cache_purge module. If not, you might need to compile Nginx from source with this module enabled, or use a Docker image that includes it.
  • Cache Key Strategy: The proxy_cache_key is vital. If your content varies by query parameters (e.g., ?lang=es), ensure your key reflects that or use proxy_ignore_headers Cache-Control and manually define proxy_cache_valid rules. For user-specific content, avoid caching entirely or implement advanced Varnish-like logic.
  • Cache Invalidation Strategy:
    • For most content, rely on Nuxt’s s-maxage and stale-while-revalidate headers. Nginx will honor them.
    • For critical, immediate updates, use the ngx_cache_purge endpoint triggered by a secure webhook.
  • HTTPS: Always use HTTPS (listen 443 ssl;). In 2026, plaintext HTTP is practically nonexistent for production sites.
  • Monitoring: Monitor your Nginx cache hits (X-Cache-Status) and your Nuxt server’s CPU/memory usage. This will show the effectiveness of your caching.
  • CDN Integration: For global reach, place a CDN (like Cloudflare, Vercel Edge Network, Netlify Edge) in front of Nginx. Your Nginx then becomes the origin for the CDN, providing another layer of caching closer to your users. Ensure CDN caching rules don’t conflict with Nginx’s.
  • Header Forwarding: Ensure Nginx correctly forwards critical headers (like Host, X-Real-IP, X-Forwarded-For) to your Nuxt server. This is essential for features like IP-based access control or analytics.
  • Downtime & Resilience: proxy_cache_use_stale is your friend. It ensures that if your Nuxt server goes down or becomes unresponsive during a revalidation, Nginx will continue serving stale content, preventing a complete outage.

Conclusion

Combining Nuxt 3’s advanced ISR capabilities with Nginx as a powerful edge cache creates a formidable architecture for high-performance, scalable web applications. You gain the best of both worlds: dynamic content with near-static site performance, reduced origin server load, and sophisticated revalidation strategies that can be tuned for both eventual consistency and immediate updates. As the web evolves, mastering these caching layers will be key to delivering exceptional user experiences and robust, cost-effective infrastructure.

What are your go-to strategies for caching Nuxt 3 applications at scale? Have you encountered unique challenges with stale-while-revalidate or ngx_cache_purge in production? Share your insights below!

Comments

No comments yet. Be the first!

We use cookies to enhance your browsing experience, serve personalized content, and analyze our traffic. By clicking "OK", you consent to our use of cookies and agree to our Terms of Service & Privacy Policy.