Astro CDN Integration

Introduction

An Astro site can keep its generated HTML on the application origin while delivering compiled stylesheets and JavaScript through a CDN. Visitors receive the same pages, but the static build assets are fetched from CDN edge servers.

This guide shows how to configure a CDN Service Domain for an Astro static build. The setup uses Astro 7.3.5 and serves the assets generated under _astro/ through CDNsun.

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 Astro

  1. Open astro.config.mjs in the Astro project root. Set build.assetsPrefix to the HTTPS URL of your CDN Service Domain: 
    import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
  vite: { build: { assetsInlineLimit: 0 } },
  build: {
    assetsPrefix: 'https://barsoom-cdn.cdnsun.org',
    inlineStylesheets: 'never'
  }
});

    Replace the sample domain with your CDN Service Domain and retain any other existing project settings. assetsPrefix changes links to Astro-generated assets without moving the HTML page to the CDN. The inlineStylesheets and assetsInlineLimit settings keep the stylesheet and small processed scripts in external files so they can be delivered through the CDN in this setup.

  2. Import the stylesheets and scripts that Astro should process from the project's src/ directory. For example, the Barsoom page imports a stylesheet from its frontmatter and uses a processed client-side script: 
    ---
import '../styles/global.css';
---

<button id="asset-check" type="button">Test interactive script</button>

<script>
  document.querySelector('#asset-check')?.addEventListener('click', () => {
    document.querySelector('#asset-check').textContent = 'Script verified';
  });
</script>

    Leave the script as a normal Astro-processed script. A script marked is:inline bypasses Astro's bundling and does not become an external CDN asset. Files placed in public/ are copied as-is rather than processed by this build setting, so handle their URLs separately if they also need CDN delivery.

  3. Build the site from the project root: 
    npm run build

    Astro writes the generated HTML to dist/ and its compiled CSS and JavaScript to dist/_astro/. The generated HTML contains asset URLs beginning with the CDN Service Domain.

  4. Deploy the complete dist/ output to the website origin. Keep the _astro/ directory and its fingerprinted filenames unchanged. Each CDN asset URL must have a matching file at the same path on the origin, allowing the CDNsun Static service to fetch and cache it.
  5. Configure cross-origin access for generated assets when Astro serves JavaScript modules through the CDN Service Domain. The browser requires the appropriate CORS response header for those modules. For guidance, see Using custom fonts with CDN - setting CORS.
  6. If the site uses client-side JavaScript, try one of its interactions after deployment. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Astro 7 website with a working client-side script and static assets delivered 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

  ____       ___     _    _   
 |  _ \\    / _ \\  | \  / || 
 | |_| ||  / //\ \\ |  \/  || 
 | .  //  |  ___  ||| .  . || 
 |_|\_\\  |_||  |_|||_|\/|_|| 
 `-` --`  `-`   `-` `-`  `-`