Craft CMS CDN integration

Introduction

A CDN can deliver Craft-managed images, image transforms, stylesheets, JavaScript, and other public files from edge servers closer to visitors. Craft continues to render pages at the origin, while the browser requests selected static assets through the CDN Service Domain.

This guide shows how to configure both Craft Assets and frontend theme files using Craft's native filesystem and alias features. The procedure was tested with Craft CMS 5.10.13.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 configure a CDN in Craft CMS

  1. Configure an HTTP Pull CDN service with your Craft site's public URL as the origin. The CDN must be able to request the same public paths that visitors can request from the origin. The origin used here is https://barsoom.cdnsun.org, and the CDN Service Domain is barsoom-cdn.cdnsun.org.
  2. Add an environment variable containing the complete HTTPS URL of your CDN Service Domain to the Craft project's .env file. Do not add a trailing slash. 
    CDN_BASE_URL=https://barsoom-cdn.cdnsun.org
  3. Open config/general.php and map the environment variable to a reusable @cdn alias. Import craft\helpers\App, then add the alias to the existing aliases() configuration. If the file already defines aliases, merge @cdn into that array rather than adding a second aliases block. 
    <?php

use craft\config\GeneralConfig;
use craft\helpers\App;

return GeneralConfig::create()
    ->aliases([
        '@webroot' => dirname(__DIR__) . '/web',
        '@cdn' => App::env('CDN_BASE_URL'),
    ]);
  4. Log in to the Craft control panel and open Settings > Filesystems. Create a new Local Folder filesystem named Site Assets with the handle siteAssets. Enable Files in this filesystem have public URLs, set Base URL to @cdn/uploads, and set Base Path to @webroot/uploads. Save the filesystem.
    Craft CMS Site Assets filesystem with a CDN Base URL and local Base Path
  5. Open Settings > Assets and create a volume named Site Assets with the handle siteAssets. Select Site Assets as the Asset Filesystem. Leave Subpath empty when the volume should use the filesystem root, then save the volume. The transform filesystem can remain set to Same as asset filesystem so generated image transforms use the same CDN-backed filesystem.
    Craft CMS asset volume using the Site Assets filesystem
  6. Open Assets and upload a file to the new volume, or move existing files into it. Craft stores the files below web/uploads at the origin and generates their public URLs from @cdn/uploads. Templates that already render Craft-generated asset URLs will therefore use the CDN Service Domain automatically.
    Craft CMS Assets view containing a file in the CDN-backed Site Assets volume
  7. Update frontend templates so static theme files also use the @cdn alias. Craft's asset filesystem setting controls managed assets and transforms, but it does not rewrite hard-coded stylesheet or JavaScript URLs. For files stored as web/css/site.css and web/js/site.js, use: 
    <link rel="stylesheet" href="{{ alias('@cdn') }}/css/site.css">
<script src="{{ alias('@cdn') }}/js/site.js" defer></script>
    Apply the same pattern to other public theme files that should use the CDN. If the project builds assets with Vite, configure the build's public base URL and the Craft Vite plugin's serverPublic value instead; see the Craft Vite documentation.
  8. Clear Craft's caches after changing the configuration and templates. 
    php craft clear-caches/all
  9. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Barsoom Craft CMS frontend using CDN-hosted CSS JavaScript and a managed asset

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

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