FAQ

Common questions about CMS Assets. For technical setup, see Getting Started. For plan details, see Billing & Plans.

Does CMS Assets replace my CDN?

No. CMS Assets sits between your frontend and your CMS origin CDN. It doesn't replace your CMS's CDN — it adds a caching and control layer on top. Your CMS still hosts the original assets; CMS Assets just proxies and caches them through your own domain.

Does this work with any CMS?

Yes. CMS Assets has built-in support for Prismic, Contentful, Sanity, Shopify, Cloudinary, and Imgix (with automatic origin resolution and URL transformation for each). You can also proxy any HTTPS asset origin. See Generic Origin Mode for details.

Will this improve performance?

Yes, in most cases. Assets are cached at Cloudflare's edge network (300+ locations worldwide). After the first request, subsequent requests for the same asset are served from the edge closest to the user — typically in under 10ms.

Even if your CMS CDN is already fast, CMS Assets gives you:

An additional cache layer you control
Query param sorting (so ?w=300&fm=webp and ?fm=webp&w=300 share the same cache entry)
Optional query param stripping for configured file types
Bandwidth visibility and control

Can I use a custom domain?

Yes. You can serve assets from your own subdomain (e.g., cdn.yourdomain.com) instead of the default your-project.cmsassets.com. This requires a CNAME record pointing to proxy.cmsassets.com. See Custom Domains for full details.

The default your-project.cmsassets.com subdomain remains active alongside any custom domain.

What file types are supported?

By default, the proxy allows these file types:

Images: jpeg, jpg, png, webp, avif, svg
Documents: pdf
Video: mp4, webm, mov, m4v

If allowedTypes is configured for a project, requests returning a Content-Type that doesn't match any allowed type receive a 403 error. If allowedTypes is not configured, all content types are served.

How does caching work?

Assets are cached at the Cloudflare edge using the Cache API. The default TTL is 2 days, but you can configure it per project (from 60 seconds to 30 days).

Query parameters are included in the cache key by default, sorted alphabetically for consistency (so ?w=300&fm=webp and ?fm=webp&w=300 produce the same cache key). If stripQueryParamsFor is configured for specific file extensions, query parameters are removed from the cache key for those types — useful for preventing duplicate entries caused by CMS-generated params like ?auto=format.

What happens if the origin is down?

If the CMS origin returns an error or is unreachable:

The edge worker returns the upstream error status code
If the asset was previously cached and the cache hasn't expired, it may still be served from cache
A 10-second timeout is enforced to prevent hanging requests

Does CMS Assets track my users?

No. CMS Assets only tracks aggregate usage metrics per project:

Total requests per month
Total bandwidth per month
Last request timestamp

No user-identifiable information is stored. No cookies are set. No analytics scripts are injected.

How is bandwidth measured?

Bandwidth is measured from the Content-Length header of each response. Both cache hits and cache misses count toward your bandwidth total.

If a response doesn't include a Content-Length header, 0 bytes are recorded for that request.

Can I use CMS Assets in development?

Yes. Create a separate project for development (e.g., my-project-dev) and use it in your local environment. Set the CMS_ASSETS_URL environment variable per environment:

# .env.development
CMS_ASSETS_URL=https://my-project-dev.cmsassets.com

# .env.production
CMS_ASSETS_URL=https://my-project.cmsassets.com

What bots are blocked by default?

The default bot blocklist includes:

ahrefs
semrush
uptimerobot
python
curl
wget
libwww
node-fetch

These are matched against the User-Agent header using a case-insensitive regex. You can customize the blocked bots regex per project.

Can I have multiple projects for the same CMS repository?

Yes. You can create multiple projects pointing to the same origin. This is useful for:

Separate staging and production environments
Different caching strategies for different parts of your site
Testing configuration changes without affecting production

How do I delete a project?

Go to your dashboard, find the project, and use the delete action. Deleting a project:

Removes the project configuration
Removes the proxy configuration (the subdomain stops working immediately)
Does not delete cached assets (they expire naturally based on TTL)

FAQ