CDN Versioning & Cache Busting

Independent version control for each asset type

What is CDN Versioning?

CDN Versioning adds a custom version parameter (?1cdnver=YOUR_VERSION) to all CDN URLs. This forces browsers and CDN servers to fetch new versions of your assets when you update them, instead of serving cached old versions.

🎯 Key Benefit: When you update CSS, JavaScript, images, or other assets, simply change the version number to force all users to download the fresh files.

How to Configure

Location: 1 CDN Manager → Settings → Advanced Tab

Available Versioning Options

1. Image Versioning

Applies to: .jpg, .png, .gif, .svg, .webp, .ico, .bmp files

Toggle: Enable/disable image versioning

Version String: Enter your custom version (e.g., "1.1", "2024-10")

Example:

Before: https://img-cdn.example.com/logo.png After: https://img-cdn.example.com/logo.png?1cdnver=1.1

2. Media Versioning

Applies to: .mp4, .mp3, .webm, .ogg, .avi, .mov files

Toggle: Enable/disable media versioning

Version String: Enter your custom version

Example:

Before: https://media-cdn.example.com/video.mp4 After: https://media-cdn.example.com/video.mp4?1cdnver=1.2

3. CSS Versioning

Applies to: .css files on CSS CDN

Toggle: Enable/disable CSS versioning

Version String: Enter your custom version

Example:

Before: https://static-cdn.example.com/style.css?ver=wc-10.2.2 After: https://static-cdn.example.com/style.css?1cdnver=1.3
Note: Removes WordPress default versions and replaces with your custom version

4. JavaScript Versioning

Applies to: .js files on JavaScript CDN

Toggle: Enable/disable JavaScript versioning

Version String: Enter your custom version

Example:

Before: https://static-cdn.example.com/script.js?ver=1.0 After: https://static-cdn.example.com/script.js?1cdnver=1.4

5. Fonts Versioning

Applies to: .woff2, .woff, .ttf, .otf, .eot files

Toggle: Enable/disable fonts versioning

Version String: Enter your custom version

Example:

Before: https://fonts-cdn.example.com/font.woff2 After: https://fonts-cdn.example.com/font.woff2?1cdnver=1.5

Version String Format

You can use any string format for your versions. Common patterns:

Format Example Use Case
Semantic 1.0, 1.1, 2.0 Major/minor updates
Date 2024-10-14, 20241014 Time-based releases
Hash abc123, git-a1b2c3 Git commit based
Custom fall-release, v2-prod Named releases

Real-World Use Cases

Scenario 1: CSS Hotfix

Problem: You fixed a CSS bug but users still see the old broken styles.

Solution:

  1. Current CSS version: 1.0
  2. Update CSS Versioning to: 1.1
  3. Save settings
  4. All CSS URLs now have ?1cdnver=1.1
  5. Browsers fetch new CSS file immediately

Result: Bug fix visible to all users instantly, without clearing cache

Scenario 2: Major Site Redesign

Problem: Complete frontend overhaul with new CSS, JS, and images.

Solution:

  1. Update all versions from 1.0 to 2.0:
    • CSS: 1.0 → 2.0
    • JS: 1.0 → 2.0
    • Images: 1.0 → 2.0
  2. Save settings
  3. All assets force refresh

Result: Complete redesign loads for all users without cache issues

Scenario 3: Staged Rollout

Problem: Want to roll out changes gradually over multiple weeks.

Solution:

  • Week 1: Update CSS version (1.0 → 1.1)
  • Week 2: Update JS version (1.0 → 1.1)
  • Week 3: Update Images version (1.0 → 2.0)

Result: Each week, only changed assets refresh, others use cache

Technical Details

Version Parameter

1 CDN Manager uses 1cdnver as the version parameter name (not standard ver).

Why 1cdnver? Using a unique parameter name prevents conflicts with WordPress core and plugin default versions, ensuring your custom version is always used.

Aggressive Replacement

The plugin removes ALL existing version parameters before adding yours:

This ensures WordPress default versions (like ?ver=wc-10.2.2) are completely replaced.

Query String Handling

If a URL already has query parameters, the version is appended:

Original: https://cdn.example.com/file.css?param=value Result: https://cdn.example.com/file.css?param=value&1cdnver=1.3

📖 How-To: Step-by-Step Versioning Guide

Scenario 1: You Updated Your CSS Styles

Problem

You made changes to your site's CSS but visitors are still seeing the old design because their browser cached the old stylesheet.

Solution with Versioning

  1. Make your CSS changes and save the file
  2. Go to 1 CDN Manager → Settings → Advanced Tab
  3. Find "CSS Versioning" section
  4. Make sure toggle is ON
  5. Change version number:
    • If it was 1.0 → change to 1.1
    • If it was 1.1 → change to 1.2
  6. Click "Save Changes"
  7. Clear all caches (WordPress + CDN + Browser)
  8. Result: All visitors now get the fresh CSS!

What happens behind the scenes:

Old URL: https://static-cdn.example.com/style.css?1cdnver=1.0 New URL: https://static-cdn.example.com/style.css?1cdnver=1.1 Browser sees different URL → Fetches fresh file!

Scenario 2: You Replaced Images on Your Site

Problem

You uploaded new product images with the same filename, but the old images are still showing.

Solution with Versioning

  1. Upload your new images (they replace the old ones)
  2. Go to 1 CDN Manager → Settings → Advanced Tab
  3. Find "Image Versioning" section
  4. Toggle ON (if not already)
  5. Increment version: 1.0 → 1.1
  6. Click "Save Changes"
  7. Purge CDN cache (if using Cloudflare)
  8. Result: New images appear immediately!

Scenario 3: Major Site Redesign

Problem

You're launching a complete redesign with new CSS, JS, images, and fonts.

Solution with Versioning

  1. Go to 1 CDN Manager → Settings → Advanced Tab
  2. Enable ALL versioning types:
    • ✅ Image Versioning
    • ✅ Media Versioning
    • ✅ CSS Versioning
    • ✅ JavaScript Versioning
    • ✅ Fonts Versioning
  3. Set ALL to version 2.0 (major version bump)
  4. Click "Save Changes"
  5. Deploy your redesign
  6. Purge all caches
  7. Result: Complete cache bust - everyone sees the new design!

Scenario 4: Troubleshooting - Changes Not Showing

Problem

You updated files and changed version numbers, but changes still aren't showing.

Troubleshooting Checklist

  1. Verify versioning is enabled
    • Check toggle is ON for the asset type
    • Verify version string is not empty
  2. Clear WordPress cache
    • WP Rocket, W3 Total Cache, etc.
    • Or: 1 CDN Manager → Tools → Clear Cache
  3. Purge CDN cache
    • Cloudflare: Purge Everything
    • Or use plugin's Cloudflare integration
  4. Hard refresh browser
    • Windows: Ctrl + Shift + R
    • Mac: Cmd + Shift + R
    • Or open incognito/private window
  5. Verify in page source
    • Right-click → View Page Source
    • Search for ?1cdnver=
    • Check if your new version is there

Scenario 5: Using Different Versions for Different Assets

Use Case

You want to track changes separately for CSS, JS, and images.

Solution

Each asset type can have its own version number!

Images: Version 1.5 (Updated product photos) CSS: Version 2.0 (Major style changes) JavaScript: Version 1.8 (Minor bug fixes) Fonts: Version 1.0 (No changes) Media: Version 1.2 (New promo video)

Benefit: Clear tracking of what changed and when

  • Changelog shows: "v2.0 - Updated CSS with new color scheme"
  • Later: "v1.6 - Updated product images"
  • Even later: "v1.9 - Fixed JavaScript cart bug"

Best Practices

Troubleshooting

Old versions still loading?

  1. Clear WordPress cache (if using caching plugin)
  2. Clear browser cache
  3. Check page source - verify new version parameter is present
  4. Purge CDN cache (Cloudflare, etc.)

Version not showing in URL?

  1. Verify versioning toggle is enabled for that asset type
  2. Verify version string is not empty
  3. Check that CDN is enabled for that asset type
  4. Test with Tools → Test CDN