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
Copy file name to clipboardExpand all lines: README.md
+69-28Lines changed: 69 additions & 28 deletions
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
Easy, opinionated CDN cache header handling.
4
4
5
-
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.
5
+
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.
6
6
7
7
e.g.
8
8
@@ -25,38 +25,86 @@ import { CacheHeaders } from "jsr:@ascorbic/cdn-cache-control";
25
25
26
26
## Usage
27
27
28
-
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 headers.
28
+
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.
29
+
30
+
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.
29
31
30
32
### Use cases
31
33
32
-
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 `revalidatable` method. This is sometimes called "on-demand ISR":
34
+
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:
33
35
34
36
```javascript
35
37
import { CacheHeaders } from"cdn-cache-control";
36
38
37
-
constheaders=newCacheHeaders().revalidatable();
39
+
constheaders=newCacheHeaders();
38
40
```
39
41
40
-
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, but to revalidate it after that time. 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` header to allow the CDN to serve a `304 Not Modified` response when the content hasn't changed.
42
+
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.
43
+
44
+
#### stale-while-revalidate
41
45
42
-
You can enable `stale-while-revalidate` with the `swr` method:
46
+
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):
43
47
44
48
```javascript
45
49
import { CacheHeaders } from"cdn-cache-control";
46
50
47
51
constheaders=newCacheHeaders().swr();
48
52
```
49
53
50
-
This tells the CDN to serve stale content for up to a year while revalidating the content in the background. It calls `revalidatable` internally, so you don't need to call both.
51
-
52
-
You can set the time-to-live either by passing a value to `revalidatable`, or with the `ttl` method:
54
+
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):
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.
65
+
66
+
```javascript
67
+
import { CacheHeaders } from"cdn-cache-control";
68
+
constheaders=newCacheHeaders().immutable();
69
+
```
70
+
71
+
This will set the CDN and browser caches to expire in 1 year, and add the immutable directive.
72
+
73
+
#### Cache tags
74
+
75
+
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. 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.
0 commit comments