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
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.
8
+
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.
17
9
18
10
e.g.
19
11
@@ -28,67 +20,43 @@ const headers = new CacheHeaders().ttl(ONE_MINUTE).swr();
28
20
npm install cdn-cache-control
29
21
```
30
22
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:
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:
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.
31
+
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.
45
32
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.
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.
49
34
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.
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.
57
36
58
37
### Use cases
59
38
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:
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:
62
40
63
41
```javascript
64
42
import { CacheHeaders } from"cdn-cache-control";
65
43
66
44
constheaders=newCacheHeaders();
67
45
```
68
46
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.
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.
76
48
77
49
#### stale-while-revalidate
78
50
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):
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):
81
52
82
53
```javascript
83
54
import { CacheHeaders } from"cdn-cache-control";
84
55
85
56
constheaders=newCacheHeaders().swr();
86
57
```
87
58
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
91
-
revalidate):
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):
@@ -98,31 +66,25 @@ const headers = new CacheHeaders().swr().ttl(ONE_HOUR);
98
66
99
67
#### Immutable content
100
68
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.
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.
104
70
105
71
```javascript
106
72
import { CacheHeaders } from"cdn-cache-control";
107
73
constheaders=newCacheHeaders().immutable();
108
74
```
109
75
110
-
This will set the CDN and browser caches to expire in 1 year, and add the
111
-
immutable directive.
76
+
This will set the CDN and browser caches to expire in 1 year, and add the immutable directive.
112
77
113
78
#### Cache tags
114
79
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
117
-
call it with a string or array of strings.
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.
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
144
-
object with the header names and values.
103
+
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.
// The `Response` constructor accepts the object directly
152
-
returnnewResponse("Hello", { headers });
109
+
const headers =newCacheHeaders().swr();
110
+
// The `Response` constructor accepts the object directly
111
+
returnnewResponse("Hello", { headers });
153
112
}
154
113
```
155
114
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:
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:
159
116
160
117
```astro
161
118
---
162
119
import { CacheHeaders, ONE_HOUR } from "cdn-cache-control";
163
120
164
121
new CacheHeaders().swr(ONE_HOUR).copyTo(Astro.response.headers);
165
122
---
123
+
166
124
```
167
125
168
126
## API
@@ -223,37 +181,36 @@ Number of seconds in one year
0 commit comments