How to Self-Host Your Next.js Application – Configuration, Caching, and Deployment Strategies

Image Optimization

Image optimization via next/image works out of the box with next start. You can also configure a custom image loader in next.config.js for static exports or external services.

• Images are optimized at runtime, not during build
• Can be disabled while retaining layout and format benefits
• On Linux (glibc), additional memory tuning may be required

Proxy Support

Proxy works automatically when self-hosting with next start. It uses the Edge runtime for low-latency logic before routes or assets are served.

• Not supported in static exports
• Use full Node.js runtime if Edge APIs are insufficient
• For advanced logic, consider Server Components or custom servers

Environment Variables

Next.js supports both build-time and runtime environment variables:

• Server-only by default
• Expose to client with NEXT_PUBLIC_ prefix
• Runtime variables are evaluated during dynamic rendering

const value = process.env.MY_VALUE

Caching and ISR

Next.js caches static pages, ISR outputs, and assets automatically. The default cache is stored on disk and in memory.

• Immutable assets: Cache-Control: public, max-age=31536000, immutable
• ISR pages: s-maxage and stale-while-revalidate
• Dynamic pages: private, no-cache, no-store

Custom Cache Handler

To share cache across containers or disable in-memory caching:

// next.config.js
module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0,
}

Example cache-handler.js:

const cache = new Map()

module.exports = class CacheHandler {
  async get(key) { return cache.get(key) }
  async set(key, data, ctx) {
    cache.set(key, { value: data, lastModified: Date.now(), tags: ctx.tags })
  }
  async revalidateTag(tags) {
    tags = [tags].flat()
    for (let [key, value] of cache) {
      if (value.tags.some(tag => tags.includes(tag))) {
        cache.delete(key)
      }
    }
  }
  resetRequestCache() {}
}

Build Cache and Versioning

Use a consistent build ID across containers:

generateBuildId: async () => process.env.GIT_HASH

Next.js detects version skew and reloads assets when needed. Use localStorage or URL state to persist data across reloads.

Streaming and Suspense

Streaming is supported in the App Router. To enable it behind Nginx:

// next.config.js
headers: [
  {
    source: '/:path*{/}?',
    headers: [{ key: 'X-Accel-Buffering', value: 'no' }],
  },
]

Static Assets and CDN Usage

Use assetPrefix to host assets on a separate domain or CDN:

assetPrefix: 'https://cdn.example.com'

Dynamic pages will include Cache-Control: private to prevent CDN caching. Static pages will include Cache-Control: public.

Conclusion

Self-hosting your Next.js application gives you full control over caching, environment variables, streaming, and deployment. With proper configuration, you can scale across containers, optimize performance, and maintain consistency across environments.