Kirby CDN integration in 2026

Introduction

A Kirby CDN integration can deliver stylesheets, JavaScript, managed images, and other public files from edge servers closer to site visitors. Dynamic pages and Panel routes remain on the Kirby origin while the CDN handles repeat requests for static content.

This guide shows how to use Kirby's native custom URL configuration for both the assets and media directories. The procedure was tested with Kirby 5.5.3.

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 Kirby

  1. Add the origin site URL and the complete HTTPS URL of the CDN Service Domain to the environment used by the Kirby application: 
    SITE_BASE_URL=https://barsoom.cdnsun.org
CDN_BASE_URL=https://barsoom-cdn.cdnsun.org

    Keeping these values outside the application code lets each deployment use its own origin and CDN Service Domain without changing templates.

  2. Open the root index.php file. After loading Kirby's bootstrap file, normalize the environment values and prepare the URL configuration: 
    <?php

require __DIR__ . '/kirby/bootstrap.php';

$siteBaseUrl = rtrim((string) getenv('SITE_BASE_URL'), '/');
$cdnBaseUrl = rtrim((string) getenv('CDN_BASE_URL'), '/');
$urls = [];

if ($siteBaseUrl !== '') {
    $urls['index'] = $siteBaseUrl;
}

if ($cdnBaseUrl !== '') {
    $urls['assets'] = $cdnBaseUrl . '/assets';
    $urls['media'] = $cdnBaseUrl . '/media';
}

    The index URL keeps site pages and Panel routes on the origin. The other two entries give Kirby separate public base URLs for static project assets and files in its generated media directory.

  3. In the same index.php file, pass the prepared URL array when creating the Kirby instance: 
    echo (new Kirby([
    'urls' => $urls,
]))->render();

    When CDN_BASE_URL is empty, Kirby retains its normal local asset and media URLs. When it is present, the configured directories use the CDN Service Domain.

  4. Keep project stylesheets and JavaScript under the public assets directory. In each template or snippet, build their absolute URLs from Kirby's configured assets URL: 
    <?= css(
    $kirby->url('assets') . '/css/app.css'
) ?>

<?= js(
    $kirby->url('assets') . '/js/app.js',
    ['defer' => true]
) ?>

    Using $kirby->url('assets') ensures that the generated stylesheet and script tags begin with the CDN Service Domain instead of the origin URL.

  5. Continue generating URLs for uploaded or content-managed files through Kirby file objects. For example, a page image can be rendered as follows: 
    <?php if ($image = $page->image('hero.jpg')): ?>
    <img
        src="<?= esc($image->url()) ?>"
        alt="Page hero image"
    >
<?php endif ?>

    Kirby places the public file in its media directory and generates its URL from the configured media base. The resulting URL therefore uses the CDN Service Domain without changing the original content file location.

  6. Update remaining literal references to files under /assets so they use $kirby->url('assets'). Keep page links, forms, API requests, Panel URLs, and other dynamic routes on the origin site URL.
  7. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Kirby site loading CSS, JavaScript, and managed media through 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.
    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

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