Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,33 @@ To roll back, pin the `site` image to a previous `sha-<commit>` tag and run
`docker compose up -d`. To build locally instead of pulling, run
`docker compose up -d --build`.

### Caching

The site sets its own `Cache-Control` headers, in the `headers` of
[`next.config.js`](next.config.js), so they are the same in the Docker image
and on Vercel:

| Paths | `Cache-Control` |
| -------------------------------------------------------- | ------------------------------------------------------ |
| `/_next/static/` (JavaScript, CSS, fonts; hashed names) | `public, max-age=31536000, immutable` (set by Next.js) |
| `/_next/image` (optimized images) | source's max-age, at least 4 hours (Next.js default) |
| Pages | `public, max-age=0, must-revalidate` |
| Other files of `public/` (images, logos, flags, favicon) | `public, max-age=86400, stale-while-revalidate=604800` |
| `robots.txt`, `sitemap.xml`, `sitemap-<n>.xml` | `public, max-age=3600` |
| `sw.js` (removes the old PWA's worker, see above) | `no-cache, no-store, must-revalidate` |

Caches revalidate pages on every request (a cheap `304 Not Modified` if a
page hasn't changed), so a deploy shows at once, and no cache serves a page
that points at `/_next/static/` files of an older image. Files of `public/`
have no hash in their names, so a changed image can take up to a day to
show, and a cache may serve the old one once more on a visit within the
following week (`stale-while-revalidate`); to replace one at once, give it a
new file name. 404s for unknown paths are not cached. A reverse proxy in front of the site should pass these
headers on and needs no cache rules of its own.
[`src/test/cache-policy.test.ts`](src/test/cache-policy.test.ts) checks
which rule applies to which path, and that every file in `public/` gets the
policy meant for it.

## Contributing

Contributions are welcome! Report problems with the website or suggest
Expand Down
50 changes: 50 additions & 0 deletions next.config.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,52 @@
// @ts-check

// Cache policy (see "Caching" in the README). Next.js itself gives the hashed
// files under /_next/static/ `public, max-age=31536000, immutable`, which
// can't be overridden, and optimized images (/_next/image) the larger of
// `images.minimumCacheTTL` (Next.js default: 4 hours) and the max-age of the source image.
// The rules below cover everything else; where several match a path, the
// last one wins. `src/test/cache-policy.test.ts` checks them.
/** @type {Awaited<ReturnType<NonNullable<import('next').NextConfig['headers']>>>} */
const cacheHeaders = [
// Pages (and any other path without a file extension, such as future route
// handlers): caches must revalidate them on every request (cheap, by ETag).
// Next.js would send `s-maxage=31536000` for prerendered pages, which would
// let a shared cache (e.g., a reverse proxy) serve a page for a year after
// a deploy, pointing at /_next/static/ files that the new image no longer
// has.
{
source: '/:path((?!_next/).*)',
headers: [
{ key: 'Cache-Control', value: 'public, max-age=0, must-revalidate' },
],
},
// Files of public/ (images, flags, logos, favicon): their names have no
// hash, so they are cached for a day only, and served stale for up to a
// week while they are revalidated in the background.
{
source: '/:path((?!_next/).*\\.[A-Za-z0-9]+)',
headers: [
{
key: 'Cache-Control',
value: 'public, max-age=86400, stale-while-revalidate=604800',
},
],
},
// robots.txt and the sitemaps (written by next-sitemap on build)
{
source: '/:file(robots\\.txt|sitemap(?:-\\d+)?\\.xml)',
headers: [{ key: 'Cache-Control', value: 'public, max-age=3600' }],
},
// The service worker that removes the old one (public/sw.js) must always
// be fetched fresh.
{
source: '/sw.js',
headers: [
{ key: 'Cache-Control', value: 'no-cache, no-store, must-revalidate' },
],
},
];

/** @type {import('next').NextConfig} */
const nextConfig = {
// Don't generate AGENTS.md in the repository on `next dev`
Expand All @@ -15,6 +62,9 @@ const nextConfig = {
},
],
},
async headers() {
return cacheHeaders;
},
// Pages that moved; old links and bookmarks keep working (permanent, so
// search engines move to the new address)
async redirects() {
Expand Down
104 changes: 104 additions & 0 deletions src/test/cache-policy.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
import { readdirSync } from 'node:fs';
import { relative, resolve, sep } from 'node:path';
// Not a public API, but the function that `next build` uses to compile the
// `source` of each rule, so the tests match paths exactly as Next.js does.
import { buildCustomRoute } from 'next/dist/lib/build-custom-route';
import { describe, expect, it } from 'vitest';
import nextConfig from '../../next.config.js';

type Header = { key: string; value: string };
type HeaderRoute = { source: string; headers: Header[] };

const publicDir = resolve(__dirname, '../../public');

const listFiles = (dir: string): string[] =>
readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
entry.isDirectory()
? listFiles(resolve(dir, entry.name))
: [resolve(dir, entry.name)],
);

// The `Cache-Control` header that the rules of `next.config.js` give a path,
// matched the way Next.js matches them: where several rules set it, the last
// matching one wins (as documented for `headers` in next.config.js).
const cacheControlFor = async (path: string): Promise<string | undefined> => {
const routes = ((await nextConfig.headers?.()) ?? []) as HeaderRoute[];
let value: string | undefined;
for (const route of routes) {
const { regex } = buildCustomRoute('header', route);
if (new RegExp(regex, 'i').test(path)) {
const header = route.headers.find(
({ key }) => key.toLowerCase() === 'cache-control',
);
value = header?.value ?? value;
}
}
return value;
};

const PAGE = 'public, max-age=0, must-revalidate';
const ASSET = 'public, max-age=86400, stale-while-revalidate=604800';
const CRAWLER = 'public, max-age=3600';
const WORKER = 'no-cache, no-store, must-revalidate';

describe('cache policy in next.config.js', () => {
it.each(['/', '/products', '/contributors', '/privacy', '/nodes/'])(
'makes caches revalidate the page %s on every request',
async (path) => {
expect(await cacheControlFor(path)).toBe(PAGE);
},
);

it.each([
'/elixir.png',
'/favicon.ico',
'/flags/de.svg',
'/contributors/alex_kanitz.jpg',
'/ELIXIR%20On-Cloud%20Logo%20Pack/On-Cloud_MONO.svg',
])('caches the file %s for a day', async (path) => {
expect(await cacheControlFor(path)).toBe(ASSET);
});

it.each(['/robots.txt', '/sitemap.xml', '/sitemap-0.xml'])(
'caches %s for crawlers for an hour',
async (path) => {
expect(await cacheControlFor(path)).toBe(CRAWLER);
},
);

it('never caches the service worker', async () => {
expect(await cacheControlFor('/sw.js')).toBe(WORKER);
});

it.each([
'/_next/static/chunks/main.js',
'/_next/static/media/font.woff2',
'/_next/image',
])('leaves %s to Next.js', async (path) => {
expect(await cacheControlFor(path)).toBeUndefined();
});

// Special files get their own rule, all others the rule for files.
const specialFiles: Record<string, string> = {
'/robots.txt': CRAWLER,
'/sw.js': WORKER,
};
const expectedFor = (path: string): string =>
specialFiles[path] ??
(/^\/sitemap(-\d+)?\.xml$/.test(path) ? CRAWLER : ASSET);

it('gives every file in public/ the policy meant for it', async () => {
const files = listFiles(publicDir).map(
(file) =>
'/' +
relative(publicDir, file)
.split(sep)
.map((part) => encodeURIComponent(part))
.join('/'),
);
expect(files).toContain('/sw.js');
for (const path of files) {
expect(await cacheControlFor(path), path).toBe(expectedFor(path));
}
});
});