Nuxt CDN Integration

Introduction

Nuxt can serve its production JavaScript, CSS, and other compiled static assets through a CDN while the application continues to render pages on its origin. This separates asset delivery from page rendering without moving dynamic routes to the CDN.

This guide shows how to configure a CDN Service Domain for a server-rendered Nuxt application using Nuxt 4.5.2. It covers the built assets generated by Nuxt and keeps the application pages on the origin.

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 Nuxt

  1. Open the Nuxt project's nuxt.config.ts file. In the app configuration, set cdnURL to the complete HTTPS URL of your CDN Service Domain. The Barsoom configuration used for this guide also names the generated asset directory explicitly: 
    export default defineNuxtConfig({
  css: ['~/assets/css/main.css'],
  app: {
    buildAssetsDir: '/nuxt-assets/',
    cdnURL: 'https://barsoom-cdn.cdnsun.org/'
  }
})

    Replace the sample domain with your CDN Service Domain and retain any other settings already in your configuration. The css entry includes the application's global stylesheet in the production build. The buildAssetsDir value determines the path used for compiled files on both the origin and CDN; Nuxt uses /_nuxt/ by default if it is omitted. The cdnURL value is used for production asset links, so local development can remain on the origin.

  2. Keep CSS and other assets that should be processed by Nuxt inside the application source and import them through Nuxt or its components. Nuxt then includes those resources in its production build. A literal root-relative URL such as /logo.svg is not automatically rewritten merely because cdnURL is set; handle such public/ files separately if they also need CDN delivery.
  3. Build the production application from the project root: 
    npm run build

    The build places the server output under .output/server/ and the public files under .output/public/. With the configuration above, compiled CSS and JavaScript are under .output/public/nuxt-assets/. The generated page references those files through the CDN Service Domain.

  4. Deploy the complete .output/ directory through your normal Nuxt production deployment. Keep the generated filenames and directory paths unchanged. The application origin must serve each compiled file at the same path that appears in its CDN URL, for example /nuxt-assets/ with the configuration above. The CDNsun Static service can then retrieve and cache those files from the origin.
  5. Allow the application origin to return the appropriate cross-origin headers for the generated asset path. Nuxt loads its JavaScript as modules from the CDN Service Domain, and the browser requires CORS for those cross-origin requests. See Using custom fonts with CDN - setting CORS for the CDN CORS setup. After changing asset response headers, ensure the CDN receives the updated responses before relying on previously cached asset URLs.
  6. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Nuxt 4 application with compiled CSS and JavaScript loaded through CDNsun

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.
    Frontend HTML proof that static assets are loaded from the 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.

Contact Us

  _  __    ______  __    __  
 | |/ //  /_   _// \ \\ / // 
 | ' //    -| ||-   \ \/ //  
 | . \\    _| ||_    \  //   
 |_|\_\\  /_____//    \//    
 `-` --`  `-----`      `