Next.js CDN integration

Introduction

A Next.js CDN integration can deliver compiled JavaScript, CSS, and imported build assets from edge servers closer to application visitors. The Next.js server remains on the application origin while the CDN handles versioned files under /_next/static/.

This guide shows how to configure the native Next.js assetPrefix option and deploy a self-hosted production application with standalone output. The procedure was tested with Next.js 16.3.4 and React 19.2.8.

Before you start

This tutorial shows how to integrate a CDN service into a website. In this particular demo example we will use:
- barsoom-cdn.cdnsun.org as the CDN Service Domain, and
- https://barsoom.cdnsun.org as the website URL (i.e. barsoom.cdnsun.org is the Origin Domain).
Please visit the Services/How-To section to obtain your CDN Service Domain.
Before you take any steps please back up your files and database.
To integrate a CDN service on https:// website the CDN service must have SSL enabled.
If your website embeds custom fonts then please first enable CORS for them.
Before you take any steps please make sure that your CDN Service Domain is ready-to-use here.

Create CDN Static service

Please refer to Creating a CDN Static service for more details.

How to enable CDN in Next.js

Open next.config.mjs in the project root. Set the production assetPrefix to the complete HTTPS URL of your CDN Service Domain. This example also enables the standalone output used for the self-hosted deployment:
```
import { PHASE_DEVELOPMENT_SERVER } from 'next/constants.js'

const configureNext = (phase) => {
  const isDev = phase === PHASE_DEVELOPMENT_SERVER

  return {
    assetPrefix: isDev
      ? undefined
      : 'https://barsoom-cdn.cdnsun.org',
    output: 'standalone',
  }
}

export default configureNext
```
The conditional value keeps the development server on its normal origin. During a production build, Next.js prefixes generated JavaScript and CSS URLs under /_next/static/ with the CDN Service Domain.
Keep application styles and build assets inside the Next.js module graph. For example, import a stylesheet from the root layout and reference local media from component CSS:
```
import './globals.css'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}
```
```
.nextMark {
  background-image: url('./assets/next.svg');
}
```
Next.js emits processed assets with versioned filenames under /_next/static/, where assetPrefix applies to their production URLs.
Treat files in the project public/ directory separately. Next.js serves them from root-relative paths, and assetPrefix does not change their URLs. Use an explicit CDN URL when a public file should also load from the CDN Service Domain.
Create the production build from the project root:
```
npm run build
```
The build writes the minimal Node.js runtime to .next/standalone/ and the CDN-addressed static files to .next/static/.
Add the static and public directories to the standalone deployment, then copy the complete standalone directory to the application origin:
```
cp -r public .next/standalone/
cp -r .next/static .next/standalone/.next/
```
Keep the generated directory structure unchanged. The CDNsun Static service requests the same /_next/static/ paths from the Next.js origin in Pull mode.
Start the production Next.js server from the deployed standalone directory:
```
cd .next/standalone
HOSTNAME=127.0.0.1 PORT=3100 node server.js
```
Run this command under a process manager and place a reverse proxy such as Nginx in front of the local Next.js port. The public application hostname remains the origin configured for the CDN Static service.
Complete the cross-origin asset setup described in the CORS configuration guide.
Rebuild and deploy the complete output whenever application assets change. Next.js creates new versioned filenames for changed files, so each deployment must keep its server runtime and .next/static/ directory from the same build.
Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.

Verify & Troubleshoot

View HTML source code of your web pages to verify that you are using CDN, you should see source attribute of your images, CSS, JavaScript, etc. beginning with your CDN Service Domain.
Don't see your CDN Service Domain in the source code of your web pages? If your website is using any cache plug-in/mechanism then you might want to clear/flush its cache.
Having trouble with custom fonts? Please refer to Using custom fonts with CDN - setting CORS for more details.
Still having trouble? Check your CDN URLs using our content check tool or please refer to Debugging a CDN service for more hints.

Introduction

Before you start

Create CDN Static service

How to enable CDN in Next.js

Verify & Troubleshoot

Contact Us