React CDN integration

Introduction

A React CDN integration can deliver production JavaScript, CSS, images, and other static assets from edge servers closer to application visitors. The application document remains on the origin while the CDN handles the files generated by the frontend build.

This guide shows how to configure the Vite public base path for a production React application and use a CDNsun Static service in Pull mode. The procedure was tested with React 19.2.8 and Vite 8.2.2.

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 React

1. Open vite.config.js in the React project root. Set the production base option to the complete HTTPS URL of your CDN Service Domain:

   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   
   export default defineConfig(({ command }) => ({
     base: command === 'build'
       ? 'https://barsoom-cdn.cdnsun.org/'
       : '/',
     plugins: [react()],
   }))

   The conditional value keeps the local Vite development server on its normal root path. During a production build, Vite prefixes generated asset URLs with the CDN Service Domain.

2. Import component assets so Vite includes them in the build and rewrites their production URLs. For example:

   import heroImage from './assets/hero.png'
   import './App.css'
   
   export default function App() {
     return <img src={heroImage} alt="Application preview" />
   }

   Vite fingerprints imported JavaScript, CSS, images, and other supported assets. Avoid constructing root-relative asset paths as runtime strings because Vite cannot rewrite values that it does not process during the build.

3. Create the production build from the project root:

   npm run build

   Vite writes the deployable application to dist/. Its generated HTML references fingerprinted files under the configured CDN Service Domain.

4. Deploy the complete contents of dist/ to the application origin. Keep every generated filename and directory unchanged so the CDNsun Static service can retrieve the same asset paths from the origin in Pull mode.
5. Complete the cross-origin asset setup described in the CORS configuration guide. This is required when the production JavaScript modules load from a different domain.
6. Rebuild and redeploy the application whenever its frontend assets change. Vite generates new fingerprinted filenames for changed files, allowing the new version to use fresh CDN URLs without overwriting cached files from the previous build.
7. 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.