Skip to main content

​
CDN & performance

All stored files in your application are available over the ButterCMS CDN, making it fast for your customers to download those assets as needed.

​
CDN benefits

  • Global Distribution - Content served from edge locations worldwide
  • Automatic Caching - Reduced load times for repeat visits
  • High Availability - Reliable image delivery
  • SSL/HTTPS - Secure image serving

​
CDN URL structure

https://cdn.buttercms.com/[file-identifier]
Example: 
https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD

​
Understanding CDN URLs

All files you upload to your ButterCMS account will have a ButterCMS CDN URL. Files in the Media Library are assigned a random CDN URL slug so that each asset has its own unique URL.

​
Example URLs

TypeExample
ButterCMS CDN URLhttps://cdn.buttercms.com/Cw5z1qzSq5qtVMCbUDwQ
Your desired URLhttps://mywebsite.com/HeadlessCMSvsTraditionalCMS.pdf
A URL on your site (e.g. https://mywebsite.com/HeadlessCMSvsTraditionalCMS.pdf) cannot link to a file in ButterCMS (e.g. https://cdn.buttercms.com/Cw5z1qzSq5qtVMCbUDwQ) since that asset resides on your domain. If you want to redirect a URL to an asset stored in your ButterCMS media library, you’ll need to set up a URL route in your web application that is hardcoded to load the asset from ButterCMS.

​
Setting up custom URL redirects

If you want to set up multiple redirects for ButterCMS media assets, follow these steps:

​
Step 1: create a resources Collection

Create a “Resources” Collection in ButterCMS with:
  • A Name short text field
  • A Resource media field
Field NameField TypePurpose
NameShort TextURL-friendly slug for the resource
ResourceMediaThe actual file to serve

​
Step 2: add a route in your application

Create a route that matches your desired URL pattern, for example: 
mywebsite.com/files/<resource-name>/

​
Step 3: query the Collection

Look up the resource by slug (or name) in your Resources collection. 
// Example: Fetching resource from collection
const butter = require('buttercms')('your-api-key');

async function getResource(resourceName) {
  const response = await butter.content.retrieve(['resources'], {
    'fields.name': resourceName
  });
  return response.data.data.resources[0];
}

// In your route handler
app.get('/files/:resourceName', async (req, res) => {
  const resource = await getResource(req.params.resourceName);
  res.redirect(resource.resource); // Redirects to CDN URL
});

​
Step 4: proxy or redirect to the asset

Redirect users to the CDN URL (recommended), or proxy the response through your app if you need to add headers or access controls.

​
Image URL transformations

ButterCMS integrates with Filestack’s Image API, allowing you to transform images by modifying the URL. This gives you powerful optimization capabilities without changing the original file.

​
URL structure

Processing tasks can be added to any CDN URL. Tasks follow this structure: 
https://cdn.buttercms.com/TASK=option:value/FILE_ID
Multiple tasks can be chained by separating them with forward slashes: 
https://cdn.buttercms.com/TASK1=option:value/TASK2=option:value/FILE_ID

​
Common transformations

TaskExampleDescription
resizeresize=height:300Resize to 300px height
resizeresize=width:800Resize to 800px width
resizeresize=width:800,height:600Resize to specific dimensions
cropcrop=dim:[x,y,width,height]Crop to specific area
rotaterotate=deg:90Rotate by degrees
flipflipFlip image vertically
flopflopFlip image horizontally
To preserve aspect ratio, specify only width or height (for example, resize=width:800). If you set both width and height, the image is resized to those exact dimensions.

​
Examples

Original URL: 
https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD
Resize to 300px height: 
https://cdn.buttercms.com/resize=height:300/Lvv0MCF0QhCoKLSuEJzD
Resize to 800px width: 
https://cdn.buttercms.com/resize=width:800/Lvv0MCF0QhCoKLSuEJzD
Multiple transformations: 
https://cdn.buttercms.com/resize=width:800/rotate=deg:90/Lvv0MCF0QhCoKLSuEJzD
Using URL transformations creates a new optimized version of the image on the CDN, improving page load times without modifying your original file.
For more advanced image transformations, refer to the Filestack Processing API documentation.

​
Best practices

Cache Transformed Images

URL transformations are cached on the CDN, so subsequent requests are fast

Responsive Images

Use URL parameters to serve different image sizes for different screen sizes

Original Backup

Your original files are always preserved; transformations create new versions

Descriptive Names

Use SEO-friendly slugs in your Resources collection for readable URLs