Skip to content

Commit d177ca4

Browse files
angelampcostaangelampcosta
authored
[Cache] Adds a page for serving tailored content (#25981)
* Adds a page for serving tailored content * Updates after review * Update after review * Update after review
1 parent 6c27bd2 commit d177ca4

File tree

1 file changed

+268
-0
lines changed

1 file changed

+268
-0
lines changed

‎src/content/docs/cache/advanced-configuration/serve-tailored-content.mdx‎

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
1+
---
2+
title: Serving tailored content with Cloudflare
3+
pcx_content_type: concept
4+
sidebar:
5+
order: 3
6+
label: Serving tailored content
7+
---
8+
9+
import { DashButton, APIRequest } from "~/components";
10+
11+
Content negotiation is the practice of serving different versions of a resource from a single URL, tailoring the experience to the end user. Common examples include delivering content in a specific language (`Accept-Language`), optimizing for a device (`User-Agent`), or serving modern image formats (`Accept`).
12+
13+
Cloudflare's global network is designed to handle this at scale. For common scenarios such as serving next-generation images, this negotiation is streamlined with a dedicated feature. For more customized logic, Cloudflare provides a toolkit including Transform Rules, Snippets, Custom Cache Keys, and Workers, giving you granular control to ensure the right content is served to every user, every time.
14+
15+
---
16+
17+
## Use query strings
18+
19+
The [Transform Rule](/rules/transform/) method is ideal when you can create a distinct URL, such as serving content based on a visitor's location.
20+
21+
### Geolocation example
22+
23+
In this example, you run an e-commerce site and want to display prices in the local currency based on the visitor's country.
24+
25+
1. In the Cloudflare dashboard, go to the Rules **Overview** page.
26+
27+
<DashButton url="/?to=/:account/:zone/rules/overview" />
28+
29+
2. Select **Create rule** and select the option **URL Rewrite Rule**.
30+
3. Enter a descriptive name, such as `Vary by Country - Canada`.
31+
4. In **If incoming requests match...**, select **Custom filter expression**.
32+
5. Under **When incoming requests match...**, create the following expression:
33+
- **Field:** `Country`
34+
- **Operator:** `equals`
35+
- **Value:** `Canada`
36+
6. Under **Then...**
37+
- for **Path**, select **Preserve**.
38+
- for **Query**, select **Rewrite to**: **Dynamic** `loc=ca`
39+
7. Select **Save**.
40+
41+
Now, requests from Canada to `/products/item` will be transformed to `/products/item?loc=ca` before reaching your origin or the cache, creating a distinct cache entry.
42+
43+
:::note[Availability]
44+
Free, Pro, Business, and Enterprise plans
45+
:::
46+
47+
---
48+
49+
## Vary for Images
50+
51+
[Vary for Images](/cache/advanced-configuration/vary-for-images/) tells Cloudflare which variants your origin supports. Cloudflare then caches each version separately and serves the correct one to browsers without contacting your origin each time. This feature is managed via the Cloudflare API.
52+
53+
### Enable Vary for Images
54+
55+
To enable this feature, create a _variants rule_ using the API. This rule maps file extensions to the image formats your origin can serve.
56+
57+
For example, the following API call tells Cloudflare that for `.jpeg` and `.jpg` files, your origin can serve `image/webp` and `image/avif` variants:
58+
59+
<APIRequest
60+
path="/zones/{zone_id}/cache/variants"
61+
method="PATCH"
62+
json={{
63+
value: {
64+
jpeg: ["image/webp", "image/avif"],
65+
jpg: ["image/webp", "image/avif"]
66+
}
67+
}}
68+
/>
69+
70+
After creating the rule, Cloudflare will create distinct cache entries for each image variant, improving performance for users with modern browsers.
71+
72+
:::note[Availability]
73+
Pro, Business, and Enterprise plans
74+
:::
75+
76+
## Use Snippets for programmatic caching
77+
78+
[Snippets](/rules/snippets/) are self-contained JavaScript fetch handlers that run at the edge on your requests through Cloudflare. They allow you to programmatically interact with the cache, providing full control over the cache key and response behavior without changing the user-facing URL.
79+
80+
### Example: A/B testing
81+
82+
In this example, you run an A/B test controlled by a cookie named `ab-test` (with values `group-a` or `group-b`). You want to cache a different version of the page for each group.
83+
84+
1. In the Cloudflare dashboard, go to the **Snippets** page.
85+
86+
<DashButton url="/?to=/:account/:zone/rules/snippets" />
87+
88+
2. Select **Create new Snippet** and name it `ab-test-caching`.
89+
3. Paste the following code. It modifies the cache key based on the `ab-test` cookie and caches the response for 30 days.
90+
91+
```JavaScript
92+
const CACHE_DURATION = 30 * 24 * 60 * 60; // 30 days
93+
94+
export default {
95+
async fetch(request) {
96+
// Construct a new URL for the cache key based on the A/B cookie
97+
const abCookie = request.headers.get('Cookie')?.match(/ab-test=([^;]+)/)?.[1] || 'control';
98+
const url = new URL(request.url);
99+
url.pathname = `/ab-test/${abCookie}${url.pathname}`;
100+
101+
const cacheKey = new Request(url, request);
102+
const cache = caches.default;
103+
104+
let response = await cache.match(cacheKey);
105+
if (!response) {
106+
// If not in cache, fetch from origin
107+
response = await fetch(request);
108+
response = new Response(response.body, response);
109+
response.headers.set("Cache-Control", `s-maxage=${CACHE_DURATION}`);
110+
// Put the response into cache with the custom key
111+
await cache.put(cacheKey, response.clone());
112+
}
113+
return response;
114+
},
115+
};
116+
```
117+
118+
4. Save and deploy the Snippet.
119+
5. From the Snippets dashboard, select **Attach to routes** to assign the Snippet.
120+
121+
:::note[Availability]
122+
Pro, Business, and Enterprise plans
123+
:::
124+
125+
## Custom Cache Keys (Enterprise)
126+
127+
If your account is on an Enterprise plan, the [Custom Cache Keys](/cache/how-to/cache-keys) feature provides a no-code interface to define which request properties are included in the cache key.
128+
129+
Custom Cache Key options:
130+
131+
- Cache by device type
132+
- Query string option `No query string parameters except`
133+
- Include headers and values
134+
- Include cookie names and values
135+
- User: Device type, Country, Language
136+
137+
### Example: Same URL, different content
138+
139+
If your origin serves different content types (for example, `application/json` vs. `text/html`) at the same URL based on the `Accept` header, use a custom cache key to cache them separately.
140+
141+
1. In the Cloudflare dashboard, go to the **Cache Rules** page.
142+
143+
<DashButton url="/?to=/:account/:zone/caching/cache-rules" />
144+
145+
2. Select **Create rule**.
146+
3. Enter rule name, such as `Vary by Accept Header`.
147+
4. Set the condition for the rule to apply (for example, a specific hostname or path).
148+
5. Under **Cache key**, select **Use custom key**.
149+
6. Select **Add new**.
150+
- **Type**: `Header`
151+
- **Name**: `Accept`
152+
- **Value**: Add each `value`, or leave empty for all.
153+
7. Select **Deploy**.
154+
155+
This configuration creates separate cache entries based on the `Accept` header value, respecting your API's content negotiation.
156+
157+
:::note[Availability]
158+
Enterprise plans only
159+
:::
160+
161+
## Use Cloudflare Workers for advanced logic
162+
163+
For complex caching scenarios, [Cloudflare Workers](/cache/interaction-cloudflare-products/workers/) provide a full serverless environment ideal for custom logic at scale.
164+
165+
### Example: Device type – Free/Pro/Biz (without Tiered Cache)
166+
167+
This Worker detects whether a visitor is on a mobile or desktop device and creates separate cache entries for each, ensuring the correct version of the site is served and cached.
168+
169+
```JavaScript
170+
export default {
171+
async fetch(request, env, ctx) {
172+
const userAgent = request.headers.get('User-Agent') || '';
173+
const deviceType = userAgent.includes('Mobile') ? 'mobile' : 'desktop';
174+
175+
// Create a new URL for the cache key that includes the device type
176+
const url = new URL(request.url);
177+
url.pathname = `/${deviceType}${url.pathname}`;
178+
179+
const cacheKey = new Request(url, request);
180+
const cache = caches.default;
181+
182+
let response = await cache.match(cacheKey);
183+
184+
if (!response) {
185+
console.log(`Cache miss for ${deviceType} device. Fetching from origin.`);
186+
response = await fetch(request);
187+
let responseToCache = response.clone();
188+
ctx.waitUntil(cache.put(cacheKey, responseToCache));
189+
}
190+
191+
return response;
192+
},
193+
};
194+
```
195+
196+
:::note[Availability]
197+
Free and Paid plans
198+
:::
199+
200+
### Example: Device type – Enterprise (with Tiered Cache)
201+
202+
This Worker detects if a visitor is on a mobile device or a desktop and creates a separate cache entry for each, ensuring the correct version of the site is served and cached. Uses the Enterprise `cf.customCacheKey` feature.
203+
204+
```JavaScript
205+
export default {
206+
async fetch(request) {
207+
// 1. Determine the device type from the User-Agent header
208+
const userAgent = request.headers.get('User-Agent') || '';
209+
const deviceType = userAgent.includes('Mobile') ? 'mobile' : 'desktop';
210+
211+
// 2. Create a custom cache key by appending the device type to the URL
212+
const customCacheKey = `${request.url}-${deviceType}`;
213+
214+
// 3. Fetch the response. Cloudflare's cache automatically uses the
215+
// customCacheKey for cache operations (match, put).
216+
const response = await fetch(request, {
217+
cf: {
218+
cacheKey: customCacheKey,
219+
},
220+
});
221+
222+
// Optionally, you can modify the response before returning it
223+
// For example, add a header to indicate which cache key was used
224+
const newResponse = new Response(response.body, response);
225+
newResponse.headers.set("X-Cache-Key", customCacheKey);
226+
return newResponse;
227+
},
228+
};
229+
```
230+
231+
:::note[Availability]
232+
Enterprise only
233+
:::
234+
235+
## Example: Caching Next.js RSC payloads
236+
237+
A common challenge is caching content from frameworks like Next.js, which uses an `RSC` (React Server Components) request header to differentiate between HTML page loads and RSC data payloads for the same URL. Here are the best ways to handle this.
238+
239+
### Method 1: Transform Rules
240+
241+
The simplest solution is to create a [Transform Rule](/rules/transform/) that checks for the `RSC` header and adds a unique query parameter on the request, creating two distinct cacheable URLs: `/page` (for HTML) and `/page?_rsc=1` (for the RSC payload).
242+
243+
1. In the Cloudflare dashboard, go to the Rules **Overview** page.
244+
245+
<DashButton url="/?to=/:account/:zone/rules/overview" />
246+
247+
2. Select **Create rule** and select the option **URL Rewrite Rule**.
248+
3. Enter a name, such as `Vary by RSC Header`.
249+
4. In **If incoming requests match...**, select **Custom filter expression**.
250+
5. Under **When incoming requests match...**, manually edit the expression so that it checks for the presence of the `RSC` header:
251+
- `(http.request.headers["rsc"] is not null)`
252+
253+
6. Under `Then...`
254+
- for **Path**, select **Preserve**
255+
- for **Query**, select **Rewrite to**, select **Dynamic**: `_rsc=1`
256+
257+
7. Select **Save**.
258+
259+
### Method 2: Snippets or Custom Cache Keys
260+
261+
Alternatively, use [Snippets](/rules/snippets/) or [Custom Cache Keys](/cache/how-to/cache-keys) to add the `RSC` header directly to the cache key without modifying the visible URL. This provides a cleaner URL but requires more advanced configuration.
262+
263+
:::note[Availability]
264+
- Snippets: Pro, Business, Enterprise
265+
- Custom Cache Keys: Enterprise only
266+
:::
267+
268+

0 commit comments

Comments
 (0)