Understanding Sitecore Browser Caching: Validating Media Caching with DisableBrowserCaching
Caching is an important part of any Sitecore implementation, especially for content-heavy websites where images, videos, JavaScript, CSS, and other media assets are requested frequently.
In a Sitecore solution deployed behind a CDN such as Cloudflare, caching can happen at multiple layers:
Browser cache
Cloudflare/CDN cache
Web server/application cache
Sitecore media cache
Understanding how these layers interact is critical when troubleshooting media performance, cache headers, stale content, or unexpected browser behavior.
In this article, we will look at a simple Sitecore configuration change that can be used to validate browser caching behavior for media responses in a UAT environment.
The Scenario
During troubleshooting of media caching, it may be necessary to determine whether the browser is caching a response based on the headers returned by Sitecore.
For example, consider a Sitecore media URL:
https://yoursitecorewebsite.com/-/media/project/images/banner.webp
When the browser requests this resource, Sitecore can return HTTP caching headers that influence how the browser handles the response.
If caching is disabled, the browser may request the resource again instead of serving it from its local cache.
This becomes particularly useful when testing a Sitecore website behind Cloudflare because it allows us to distinguish between:
Browser Cache
↓
Cloudflare Cache
↓
CD Server
↓
Sitecore Media Handler
What is DisableBrowserCaching?
Sitecore provides the following setting:
<setting name="DisableBrowserCaching" value="true" />
This setting controls whether browser caching is disabled for Sitecore responses.
For testing purposes, we can explicitly set it to:
<setting name="DisableBrowserCaching" value="false" />
This allows browser caching behavior to be enabled and helps validate how the browser handles Sitecore media responses.
The important point is that this setting should be treated as part of a controlled caching test rather than as a complete CDN caching configuration.
The Patch File
Instead of modifying the Sitecore configuration directly, we can create a patch file under:
App_Config\Include\Project\
For example:
Project.DisableBrowserCaching.config
The patch file can contain:
<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<sitecore>
<settings>
<setting name="DisableBrowserCaching">
<patch:attribute name="value">false</patch:attribute>
</setting>
</settings>
</sitecore>
</configuration>
This approach follows Sitecore's configuration patching mechanism and avoids directly changing the original Sitecore configuration file.
Why Use a Patch Instead of Editing the Original Configuration?
Directly modifying Sitecore's default configuration is generally not recommended.
A patch file provides several benefits:
1. Easier deployment
The configuration change can be deployed independently with the application package.
2. Easier rollback
The patch can be removed or disabled without modifying the Sitecore default configuration.
3. Better maintainability
Project-specific configuration remains separate from Sitecore's standard configuration.
4. Environment-specific control
The configuration can be applied only to environments where the behavior needs to be tested.
For example:
Development
↓
UAT
↓
Production
The patch can initially be deployed to UAT without making the same change in production.
Browser Cache vs Cloudflare Cache
One of the most important concepts when troubleshooting caching is understanding that browser caching and CDN caching are different.
A simplified request flow looks like this:
User Browser
|
| Request
↓
Cloudflare
/ \
Cache HIT Cache MISS
| |
↓ ↓
Cached Response UAT CD
|
↓
Sitecore
|
↓
Media Response
A browser can have its own cached copy of the response.
Cloudflare can also have a cached copy.
Therefore, clearing or changing one cache does not necessarily affect the other.
What Does DisableBrowserCaching=false Help Us Validate?
Setting:
<patch:attribute name="value">false</patch:attribute>
allows us to test the browser caching behavior without Sitecore explicitly disabling browser caching.
This is useful when investigating questions such as:
Is the browser caching the media response?
Are cache-control headers being returned?
Is the browser requesting the resource again?
Is Cloudflare serving the resource from its edge cache?
Is the request reaching the Sitecore CD server?
Is the response different between a cached and non-cached request?
The goal is not simply to make the website faster or slower.
The goal is to identify which caching layer is responsible for the observed behavior.
How to Validate the Change
After deploying the patch to the UAT CD server, open the website and select a media resource.
For example:
https://uat.example.com/-/media/project/images/test-image.webp
Open the browser's Developer Tools.
In Chrome:
F12 → Network → Select the media request → Headers
Check the response headers.
Pay particular attention to:
Cache-Control
Expires
ETag
Last-Modified
Age
CF-Cache-Status
Content-Type
The exact headers will depend on the Sitecore configuration, web server, CDN configuration, and the resource being requested.
Checking Cloudflare
When Cloudflare is in front of the Sitecore CD server, the response may contain Cloudflare-related headers.
One useful header is:
CF-Cache-Status
Depending on the request and Cloudflare configuration, values may indicate whether the resource was served from Cloudflare's cache or fetched from the origin.
For example:
CF-Cache-Status: HIT
generally indicates that Cloudflare served the response from its cache.
Whereas:
CF-Cache-Status: MISS
indicates that Cloudflare did not serve the response from its existing cache and had to obtain it from the origin.
Testing with a Hard Refresh
For controlled testing, browser cache behavior should also be considered.
A normal refresh may allow the browser to reuse cached resources.
A hard refresh forces the browser to revalidate or retrieve resources differently depending on the browser and response headers.
For example, in Chrome:
Open DevTools
→ Network
→ Disable cache
→ Refresh the page
This is useful during troubleshooting because it allows you to compare:
Browser cache enabled
vs
Browser cache disabled
However, the DevTools Disable cache option applies while DevTools is open and should not be confused with the Sitecore DisableBrowserCaching setting.
A Simple Testing Matrix
A useful approach is to test the same media resource under different conditions.
| Test | Browser Cache | Cloudflare | Purpose |
|---|---|---|---|
| 1 | Enabled | Enabled | Simulate normal user behavior |
| 2 | Disabled | Enabled | Isolate browser caching |
| 3 | Enabled | Cache cleared | Check CDN/origin behavior |
| 4 | Disabled | Cache cleared | Validate origin response |
| 5 | Incognito | Enabled | Reduce impact of existing browser cache |
This gives a much clearer picture than repeatedly refreshing the page and assuming the request reached Sitecore.
Why This Matters for Sitecore Media
Media assets can be requested very frequently on content-heavy websites.
Typical examples include:
.jpg
.jpeg
.png
.webp
.svg
.gif
.webm
.mp4
If these resources are cached correctly, the number of requests reaching the Sitecore CD server can be significantly reduced.
The caching architecture can therefore look like:
Sitecore CD
|
| Origin Response
↓
Cloudflare
|
+------+------+
| |
Cache HIT Cache MISS
| |
↓ ↓
Browser Sitecore CD
|
↓
Local Browser Cache
The objective is to make sure each layer behaves according to the intended caching strategy.
Important: DisableBrowserCaching Is Not a CDN Configuration
A common misconception is that changing:
DisableBrowserCaching
will automatically control Cloudflare caching.
It does not.
There are multiple independent factors involved:
Browser caching
Controlled primarily through HTTP response headers and browser behavior.
Cloudflare caching
Controlled through Cloudflare cache rules, cache policies, headers, TTLs, and other CDN configuration.
Sitecore media caching
Controlled through Sitecore media handling and related caching mechanisms.
Therefore, changing one layer should not be assumed to change the behavior of the others.
Recommended Validation
For an investigation, the patch can be deployed to the CD server under:
App_Config\Include\Project\
After deployment:
Restart the CD application if required by the deployment process.
Confirm that the patch has been loaded successfully.
Open the website.
Open Developer Tools.
Navigate to the Network tab.
Request a Sitecore media item.
Inspect the response headers.
Record the
Cache-Controlresponse.Check Cloudflare-related headers such as
CF-Cache-Status.Repeat the request.
Compare the first and subsequent requests.
Test with browser cache disabled.
Compare the results with a normal browser session.
This provides evidence about where the response is being cached.
Conclusion
Caching troubleshooting in a Sitecore solution should be approached as a layered investigation rather than as a single configuration change.
The DisableBrowserCaching setting provides a useful control for validating browser caching behavior. By deploying a small configuration patch to UAT, we can test the behavior without modifying the original Sitecore configuration files.
The most important takeaway is:
Browser caching, Cloudflare caching and Sitecore media caching are separate layers and should be validated independently.
Using browser Developer Tools together with response headers such as Cache-Control and Cloudflare's CF-Cache-Status makes it possible to determine where a media response is being served from.
Once the behavior is clearly understood in UAT, the caching strategy can be reviewed before applying any corresponding changes to production.
Comments
Post a Comment