Next.js

We’ve deployed thousands of Next.js applications at scale and have optimized the sherpa.sh infrastructure for maximum Next.js performance.

When deploying Next.js to sherpa.sh you get additional performance and scalability benefits you wouldn’t get when self-hosting - with zero-configuration - thanks to our framework-defined architecture

Note

Read more about how we run Next.js at scale in our blog post: Secrets of Self-hosting Nextjs at Scale

Next.js Quickstart

To deploy your first Next.js application, follow our quick start guide. Your app will be live in ~2 minutes.

What you get out of the box:

• Zero-configuration deployments that just work
• Automatic HTTPS and custom domain support
• Built-in performance optimization
• Global, production-ready infrastructure that can scale.

Never pay for idle instances. Only pay for what you use.

Supported Versions

• Next.js 15
• Next.js 14

Supported Features

Feature	Supported by sherpa.sh
App Router	✅
Page Router	✅
Middleware functions	✅
Edge V8 Isolates	Enterprise Only
Incremental Static Regeneration (ISR)	✅
Server Side Rendering (SSR)	✅
Static Site Generation (SSG)	✅
Partial Pre-Rendering (PPR)	✅
Layout (Nested, Parallel, Error)	✅
Data Fetching Revalidate (10, 60)	✅
Data Fetching (no-store, POST default, POST without cache)	✅
Routing (default, no-cache)	✅
Static Metadata	✅
Dynamic Metadata (SSG, SSR)	✅
Image Optimization	✅
Server Actions	✅

Architecture

To maximize performance - and savings - we use framework defined infrastructure to deploy your app. You can read about our infrastructure setup in more detail on the Next.js Architecture page.

Configuration

We believe in convention over configuration. Your existing next.config.js works immediately - no additional setup required. When you need customization, our platform stays flexible.

next.config.js overrides

To prepare your application for our infrastructure, the sherpa.sh platform will override some of the values in your projects next.config.jsfile. Below you will find descriptions of the overridden values:

• assetPrefix: We deploy your static assets to a specialized static CDN. We override the assetPrefixso your app knows to ask the CDN for your static files.
• generateBuildId: We set a unique hash for each build that correlates with a deployment in the sherpa.sh portal.
• cacheHandler: We maintain a globally distributed cache to enhance performance of PPR, ASO, and other caching functionality of Next.js. Each application gets a slice of the cache. This is our custom handler for read/write/delete to your applications portion of the cache.
• cacheMaxMemorySize: Set to 0 because your application will use the global cache.
• headers: We append a cache-controlheader to your existing next.conf.jsheaders for static asset caching best practices. If you need custom control over this header, you can configure it from inside the portal.
• output: This always is set to standaloneto minimize deployment bundles and make deployments compatible with our global infrastructure.
• allowedOrigins: Set to a wildcard of your apps domain *.[YOUR_DOMAIN] to ensure your server actions and other Next.js functionality works in the global deployment setup.

Image Optimization

By default, sherpa.sh supports image optimization and respects all your Next.js config settings. Optimized images are stored in our global cache infrastructure and then served by our CDN until the content goes stale based on the cache-control headers sent by Next.js to the CDN.

Note

CDN Caching Query Params: By default, sherpa.sh will cache each individually optimized image separately in the CDN. For example, an image logo.svg that is loaded with two seaprate widths 100and 200via the query params, will have the two separate images stored in the CDN.

If you need to ignore specific query params, let us know. We can customize your setup.

Caching

By default our CDN will respect the cache control headers returned by Nextjs to the CDN. (Our CDN sits in front of the entire next application, for more info read about our architecture). With one caveat. Any endpoints at /api/* will never get cached by the CDN or the browser. Our setup will override ignore any cache-control headers on API endpoints.

Tip

If you want to see if a particular page or asset (JS, CSS, Image, etc) is being cached. You can look at the response headers of the request in developer tools for the Cdn-Cache header which will tell you if its a cache HIT or cache MISS. This info for historic requests are also available in the logging section of your portal.

Architecture

Overview

Our NextJS framework-defined architecture delivers exceptional performance and cost efficiency through a carefully designed system of CDNs, Kubernetes clustering, and distributed caching. This document explains how these components work together to serve your application.

Global Content Delivery

Your application sits behind a global CDN that acts as the primary entry point for all incoming requests. This CDN intelligently processes the cache headers returned by NextJS (cache-control, stale-while-revalidate, etc), ensuring that as many requests as possible are served directly from the CDN’s edge locations. The result is not just blazing-fast response times for your users, but also significant cost savings through our strategic CDN partnerships.

Application Deployment

We host your application in our scalable Kubernetes clusters. As request volume increases, our system automatically scales up your application’s functions behind a load balancer. This ensures smooth handling of traffic spikes while maintaining consistent performance. The containerized nature of the deployment means your application runs in identical environments across all instances, eliminating environment-related issues.

Static Asset Management

Static assets are served through a dedicated CDN, accessible via a static- subdomain prefix. This separation is achieved by configuring the NextJS assetPrefix variable during build time (See configuring Next.js). Our default caching settings for static assets are optimized for common use cases, striking a balance between performance and freshness. Soon, you’ll be able to customize these settings through our portal to match your specific needs.

Advanced Caching System

We’ve implemented a sophisticated caching system that’s co-located with your application deployment. At its heart is a custom cache-handler.js file that enables your NextJS application to quickly read and write cache data using our global caching servers. This setup ensures optimal performance and allows us to scale your application seamlessly within our Kubernetes infrastructure.

Performance and Scaling

Performance optimization happens at multiple levels in our architecture. The CDN layer maximizes cache hits while ensuring content freshness. When traffic increases, your application scales horizontally in our Kubernetes clusters, with new instances spinning up automatically to meet demand. The multi-layered caching approach combines CDN-level caching for edge performance, application-level caching for dynamic content, and static asset caching for resource optimization.

Configuration Best Practices

Our system comes with sensible defaults, but it ultimately respects the settings inside of Next.js. In most cases the default Next.js settings will provide optimum performance. That said, you have full control via Next.js and any cache-headers and performance settings you configure will be respected by our framework-defined architecture

Enterprise Features

Have a unique need? Our enterprise features deliver additional capabilities:

• Edge runtime capabilities: Run your middleware at the edge in v8 isolates.
• Custom deployment configurations: Have a special need? We can customize our platform.
• Advanced security features: If you need SOC II, HIPAA, or FedRamp certified deployments.
• Dedicated support staff: Dedicated account manager and support engineers for your company’s unique needs.