Laravel CDN integration

Introduction

A Laravel CDN integration can deliver compiled CSS and JavaScript, public application assets, and files from Laravel's public filesystem through edge servers closer to visitors. This reduces repeated traffic to the application server and can improve asset loading times.

This guide shows how to set up a CDN in Laravel with the framework's native ASSET_URL setting and public filesystem disk configuration. The procedure was tested with Laravel 13.24.0 and Vite 8.2.1.

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 Laravel

  1. Open the .env file in the Laravel project root. Set ASSET_URL to the complete HTTPS URL of your CDN Service Domain. Add a separate variable for the public filesystem URL, including its /storage path: 
    ASSET_URL=https://barsoom-cdn.cdnsun.org
FILESYSTEM_PUBLIC_URL=https://barsoom-cdn.cdnsun.org/storage

    ASSET_URL changes URLs generated by Laravel's asset() helper and prefixes production assets generated by Laravel's Vite integration.

  2. Open config/filesystems.php. In the existing public disk, replace the url value with FILESYSTEM_PUBLIC_URL. Keep the local application URL as a fallback: 
    'public' => [
    'driver' => 'local',
    'root' => storage_path('app/public'),
    'url' => env(
        'FILESYSTEM_PUBLIC_URL',
        rtrim(env('APP_URL'), '/').'/storage'
    ),
    'visibility' => 'public',
    'throw' => false,
],

    Laravel now returns the configured CDN URL when the application calls Storage::disk('public')->url().

  3. If the public storage link does not already exist, create it from the Laravel project root: 
    php artisan storage:link

    This links public/storage to storage/app/public, allowing the CDN to retrieve files stored on the public disk from the application origin.

  4. Generate asset URLs with Laravel's native helpers in Blade templates. Use @vite for compiled entry points, asset() for files in the public directory, and Storage::url() for public filesystem files: 
    @php
    $storedImage = \Illuminate\Support\Facades\Storage::disk('public')
        ->url('images/photo.jpg');
@endphp

@vite(['resources/css/app.css', 'resources/js/app.js'])

<img src="{{ asset('images/logo.svg') }}" alt="Company logo">
<img src="{{ $storedImage }}" alt="Stored image">

    Keep application routes, form actions, and other dynamic URLs on the Laravel domain. Vite does not rewrite absolute asset URLs, so use Vite-managed imports or Laravel URL helpers for files that should use the CDN Service Domain.

  5. Build the production Vite assets and rebuild Laravel's configuration cache: 
    npm run build
php artisan config:cache

    Run the build during every deployment that changes frontend assets. Laravel reads the generated Vite manifest and produces versioned CDN URLs for the compiled files.

  6. Complete the required cross-origin asset setup by following the CDNsun CORS configuration guide. This also applies when Vite's production JavaScript modules load from a different domain.
  7. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled Laravel application loading Vite, public assets, and public filesystem files 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

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