You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Modern CDNs allow very fine-grained control over the cache. This is particularly useful for server-side rendering of web content, as it allows you to manually handle the invalidation of content, ensuring it stays fast and fresh. This package provides a subclass of the `Headers` class that makes it easier to set cache control headers for content served through a modern CDN. It provides a simple, chainable API with sensible defaults for common use cases. It works by setting the `Cache-Control` and `CDN-Cache-Control` headers to the appropriate values. If run on a supported platform it will use the more specific header for that CDN. e.g. on Netlify it will use the `Netlify-CDN-Cache-Control` header.
8
+
Modern CDNs allow very fine-grained control over the cache. This is particularly
9
+
useful for server-side rendering of web content, as it allows you to manually
10
+
handle the invalidation of content, ensuring it stays fast and fresh. This
11
+
package provides a subclass of the `Headers` class that makes it easier to set
12
+
cache control headers for content served through a modern CDN. It provides a
13
+
simple, chainable API with sensible defaults for common use cases. It works by
14
+
setting the `Cache-Control` and `CDN-Cache-Control` headers to the appropriate
15
+
values. If run on a supported platform it will use the more specific header for
16
+
that CDN. e.g. on Netlify it will use the `Netlify-CDN-Cache-Control` header.
9
17
10
18
e.g.
11
19
@@ -20,43 +28,67 @@ const headers = new CacheHeaders().ttl(ONE_MINUTE).swr();
20
28
npm install cdn-cache-control
21
29
```
22
30
23
-
It is also available in [jsr](https://jsr.io) as `@ascorbic/cdn-cache-control`. If using Deno, you can import it directly without installing:
31
+
It is also available in [jsr](https://jsr.io) as `@ascorbic/cdn-cache-control`.
32
+
If using Deno, you can import it directly without installing:
The module exports a single class, `CacheHeaders`, which is a subclass of the fetch [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) class. It provides a chainable API for setting cache headers. By default it sets the `Cache-Control` and `CDN-Cache-Control` headers to sensible defaults for content that should be cached by the CDN and revalidated by the browser.
40
+
The module exports a single class, `CacheHeaders`, which is a subclass of the
class. It provides a chainable API for setting cache headers. By default it sets
43
+
the `Cache-Control` and `CDN-Cache-Control` headers to sensible defaults for
44
+
content that should be cached by the CDN and revalidated by the browser.
32
45
33
-
It can be instantiated with a `HeadersInit` value, which lets you base it on an existing `Headers` object, or an object or array with existing header values. In that case it will default to using existing `s-maxage` directives if present.
46
+
It can be instantiated with a `HeadersInit` value, which lets you base it on an
47
+
existing `Headers` object, or an object or array with existing header values. In
48
+
that case it will default to using existing `s-maxage` directives if present.
34
49
35
-
You can pass a `cdn` value as the second argument to set the CDN cache control header. In some cases this will enable targeted cache header names. e.g. for Netlify it will use the `Netlify-CDN-Cache-Control` header. Currently supported values are `netlify`, `vercel`, `cloudflare` and `akamai`. If you don't pass a value, or pass an unsupported one it will use the generic `CDN-Cache-Control` header. It will also attempt to detect the platform automatically on Vercel and Netlify.
50
+
You can pass a `cdn` value as the second argument to set the CDN cache control
51
+
header. In some cases this will enable targeted cache header names. e.g. for
52
+
Netlify it will use the `Netlify-CDN-Cache-Control` header. Currently supported
53
+
values are `netlify`, `vercel`, `cloudflare` and `akamai`. If you don't pass a
54
+
value, or pass an unsupported one it will use the generic `CDN-Cache-Control`
55
+
header. It will also attempt to detect the platform automatically on Vercel and
56
+
Netlify.
36
57
37
58
### Use cases
38
59
39
-
If you have content that you want to have the CDN cache until it is manually revalidated or purged with a new deploy, you can use the default values:
60
+
If you have content that you want to have the CDN cache until it is manually
61
+
revalidated or purged with a new deploy, you can use the default values:
40
62
41
63
```javascript
42
64
import { CacheHeaders } from"cdn-cache-control";
43
65
44
66
constheaders=newCacheHeaders();
45
67
```
46
68
47
-
This sets the `CDN-Cache-Control` header to `public,s-maxage=31536000,must-revalidate`, which tells the CDN to cache the content for a year. It sets `Cache-Control` to `public,max-age=0,must-revalidate`, which tells the browser to always check with the CDN for a fresh version. You should combine this with an `ETag` or `Last-Modified` header to allow the CDN to serve a `304 Not Modified` response when the content hasn't changed.
69
+
This sets the `CDN-Cache-Control` header to
70
+
`public,s-maxage=31536000,must-revalidate`, which tells the CDN to cache the
71
+
content for a year. It sets `Cache-Control` to
72
+
`public,max-age=0,must-revalidate`, which tells the browser to always check with
73
+
the CDN for a fresh version. You should combine this with an `ETag` or
74
+
`Last-Modified` header to allow the CDN to serve a `304 Not Modified` response
75
+
when the content hasn't changed.
48
76
49
77
#### stale-while-revalidate
50
78
51
-
You can enable `stale-while-revalidate` with the `swr` method, optionally passing a value for the time to serve stale content (defaults to one week):
79
+
You can enable `stale-while-revalidate` with the `swr` method, optionally
80
+
passing a value for the time to serve stale content (defaults to one week):
52
81
53
82
```javascript
54
83
import { CacheHeaders } from"cdn-cache-control";
55
84
56
85
constheaders=newCacheHeaders().swr();
57
86
```
58
87
59
-
This tells the CDN to serve stale content while revalidating the content in the background. Combine with the `ttl` method to set the time for which the content will be considered fresh (default is zero, meaning the CDN will always revalidate):
88
+
This tells the CDN to serve stale content while revalidating the content in the
89
+
background. Combine with the `ttl` method to set the time for which the content
90
+
will be considered fresh (default is zero, meaning the CDN will always
@@ -66,25 +98,31 @@ const headers = new CacheHeaders().swr().ttl(ONE_HOUR);
66
98
67
99
#### Immutable content
68
100
69
-
If you are serving content that is guaranteed to never change then you can set it as immutable. You should only do this for responses with unique URLs, because there will be no way to invalidate it from the browser cache if it ever changes.
101
+
If you are serving content that is guaranteed to never change then you can set
102
+
it as immutable. You should only do this for responses with unique URLs, because
103
+
there will be no way to invalidate it from the browser cache if it ever changes.
70
104
71
105
```javascript
72
106
import { CacheHeaders } from"cdn-cache-control";
73
107
constheaders=newCacheHeaders().immutable();
74
108
```
75
109
76
-
This will set the CDN and browser caches to expire in 1 year, and add the immutable directive.
110
+
This will set the CDN and browser caches to expire in 1 year, and add the
111
+
immutable directive.
77
112
78
113
#### Cache tags
79
114
80
-
Some CDNs support the use of cache tags, which allow you to purge content from the cache in bulk. The `tag()` function makes it simple to add tags. You can call it with a string or array of strings.
115
+
Some CDNs support the use of cache tags, which allow you to purge content from
116
+
the cache in bulk. The `tag()` function makes it simple to add tags. You can
The headers object can be used anywhere that accepts a `fetch``Headers` object. This includes most serverless hosts. It can also be used directly in many framework SSR functions. Some APIs need a plain object rather than a `Headers` object. For these you can use the `toObject()` method, which returns a plain object with the header names and values.
140
+
The headers object can be used anywhere that accepts a `fetch``Headers` object.
141
+
This includes most serverless hosts. It can also be used directly in many
142
+
framework SSR functions. Some APIs need a plain object rather than a `Headers`
143
+
object. For these you can use the `toObject()` method, which returns a plain
// The `Response` constructor accepts the object directly
111
-
returnnewResponse("Hello", { headers });
150
+
const headers =newCacheHeaders().swr();
151
+
// The `Response` constructor accepts the object directly
152
+
returnnewResponse("Hello", { headers });
112
153
}
113
154
```
114
155
115
-
Some frameworks use a readonly `Response` object, so you need to use an existing `headers` object. In this case you can use the `copyTo` method to copy the headers to the response:
156
+
Some frameworks use a readonly `Response` object, so you need to use an existing
157
+
`headers` object. In this case you can use the `copyTo` method to copy the
158
+
headers to the response:
116
159
117
160
```astro
118
161
---
119
162
import { CacheHeaders, ONE_HOUR } from "cdn-cache-control";
120
163
121
164
new CacheHeaders().swr(ONE_HOUR).copyTo(Astro.response.headers);
122
165
---
123
-
124
166
```
125
167
126
168
## API
@@ -181,36 +223,37 @@ Number of seconds in one year
0 commit comments