Skip to main content

Running Front-Commerce behind a CDN

How to put a CDN (e.g. Cloudflare) in front of Front-Commerce while respecting its HTTP cache contract, covering what to cache, what to never cache, and which CDN optimizations to disable.

You can place any CDN in front of Front-Commerce, as long as the CDN honors the HTTP cache headers that Front-Commerce already sets on every response. This page describes that contract, lists what is safe to cache and what must never be cached, and points out the CDN settings that break server-side rendering if left enabled. A dedicated Cloudflare checklist is included.

Self-operated CDN

This guide targets teams that operate their own CDN in front of Front-Commerce. If your project runs on Front-Commerce Cloud, the caching layer is managed for you, see Using the proxy cache.

Front-Commerce's HTTP cache contract​

Front-Commerce sets the right Cache-Control header on every response itself. You do not configure a caching strategy on the CDN, you let the CDN obey the header that Front-Commerce emits:

  • Cacheable responses get Cache-Control: public, s-maxage=<n>, stale-while-revalidate=<n>.
  • Everything else gets Cache-Control: no-cache.

Front-Commerce forces no-cache whenever the request belongs to a logged-in (non-anonymous) visitor or the response is rendered in contribution mode, so personalized content is never marked as cacheable.

The single rule for any CDN in front of Front-Commerce: honor the Cache-Control headers coming from the origin, do not define your own caching strategy. For the full reference on these headers and how to tune them, see the Cache-Control and CDN guide.

What is cacheable vs never cacheable​

Cacheable:

  • Built, content-hashed assets (JS/CSS bundles). Their file names change on every build, so they are immutable and safe to cache for a long time.
  • Resized images served under /images.resized/*, returned with Cache-Control: public, max-age=<one year>.
  • Anonymous pages that emit an s-maxage directive (e.g. product, category and home pages, /robots.txt, /sitemaps.xml).

Never cacheable:

  • /graphql.
  • /api/*, including /api/admin/*.
  • Any request carrying the session cookie connect.sid (this is the default cookie name and it is configurable).
  • Any response that contains a Set-Cookie header.
  • Any response rendered in contribution mode.

In all of these cases Front-Commerce already responds with Cache-Control: no-cache, so a compliant CDN does the right thing on its own. The two things to double-check on the CDN are: it respects the origin Cache-Control, and it never serves an authenticated request (one carrying connect.sid) from the shared cache.

Cloudflare specifics​

Cloudflare is fully compatible with Front-Commerce, but a few defaults must be adjusted. This is a checklist, not a step-by-step tutorial, the exact location of each setting changes over time in the Cloudflare dashboard.

  • ⚠️ Cloudflare does not cache HTML by default. Page responses come back as Cf-Cache-Status: BYPASS. To cache anonymous HTML pages you must add explicit Cache Rules (Cloudflare's legacy Page Rules are being retired). Static assets, on the other hand, are cached out of the box and report Cf-Cache-Status: HIT.
  • Respect the origin cache headers. Configure Cloudflare to honor the existing Cache-Control headers instead of overriding them with its own edge TTL.
  • Bypass the cache for /graphql, /api/*, and any request carrying connect.sid or any response carrying Set-Cookie.

CDN optimizations to disable​

Several Cloudflare (and CDN-generic) "performance" features rewrite the HTML or JavaScript that Front-Commerce generates. Because Front-Commerce is server-side-rendered and hydrated by React on the client, any alteration of the markup makes client hydration fail. Disable:

  • Rocket Loader.
  • Auto Minify (JS, CSS and HTML).
  • Any other feature that rewrites, injects into, or otherwise alters the HTML or JavaScript payload.

The general principle: never transform the HTML or JavaScript produced by Front-Commerce.

WAF & bots​

A Web Application Firewall and bot protection are welcome in front of Front-Commerce, but keep two principles in mind:

  • Do not block /graphql or /api/*. These are legitimate storefront routes, the whole front-end depends on them. Blocking them takes the site down.
  • Focus protection on administrative surfaces and on clearly abusive traffic, and avoid rules that block legitimate visitors or server-side rendering. Tune any aggressive ruleset against real storefront traffic before enabling it in blocking mode.

Verifying the cache​

Inspect the response headers to confirm how a given URL is being cached:

curl -I https://www.example.com/

Read the CDN status header, on Cloudflare this is Cf-Cache-Status, whose value is HIT, MISS or BYPASS. Front-Commerce itself does not emit a cache-status header, so rely on the one provided by your CDN. For a reproducible way to check the Cache-Control headers Front-Commerce sets per route, use the validation script in the Cache-Control and CDN guide.

Not yet battle-tested in production

The "customer operates their own CDN in front of Front-Commerce" scenario has not been extensively validated in production yet. Please report any issue or feedback to our support team so we can improve this guide.