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
204 changes: 70 additions & 134 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,166 +17,102 @@ memory by default, with revalidation shared across all of them.
> ElastiCache IAM. 16.4.2 setups keep working with deprecation warnings, and `^16.4.2` installs get
> it automatically. Read [Upgrading from 16.4.2](./docs/migrating.md) before you deploy.

## Quick start
## Start here

```bash
npm install --save-exact @mrjasonroy/cache-components-cache-handler
```
1. **Install** the release for your Next.js minor, pinned exact. For Next 16.4.x:

The package version follows Next.js. Pin it to the exact release for your Next.js version
(`--save-exact`; Next 16.4.3 → `16.4.3`) and upgrade the two together. A range such as `^16.4.3`
also accepts the 16.5 releases, which follow Next.js 16.5 and remove the APIs deprecated in
16.4.3. From the next release, the `next` peer dependency is `~<major>.<minor>.0` of the
package's own version (for example `~16.4.0` for 16.4.x), so npm refuses a handler whose minor
does not match your Next.js with an `ERESOLVE` error, and pnpm and Yarn warn.
```bash
npm install --save-exact @mrjasonroy/cache-components-cache-handler@16.4
```

```js
// next.config.mjs
import { withCache } from "@mrjasonroy/cache-components-cache-handler";
`@16.4` picks the newest 16.4.x and `--save-exact` pins it. Needs Node.js 22.3+.

export default withCache({ cacheComponents: true });
```
2. **Wrap your config:**

```bash
REDIS_URL=redis://cache:6379 # unset → everything stays in memory (dev, CI, previews)
```
```js
// next.config.mjs
import { withCache } from "@mrjasonroy/cache-components-cache-handler";

export default withCache({ cacheComponents: true });
```

That's it. You keep writing `"use cache"`, `cacheTag` and `revalidateTag` as Next documents them
([examples](./docs/usage.md)). `ioredis` is installed automatically as an optional dependency
([unless optionals are skipped](./docs/installation.md#install)).
3. **Pick your setup:**

| Setup | What to do |
|---|---|
| Local dev, CI, previews, one instance | Nothing. Without `REDIS_URL` everything stays in memory. |
| Redis or Valkey | Set `REDIS_URL=redis://cache:6379` on the running app. [Installation](./docs/installation.md#point-it-at-redis) |
| AWS ElastiCache, Serverless or cluster mode disabled | Set `ELASTICACHE_ENDPOINT` and `ELASTICACHE_AUTH_TOKEN`, or the IAM variables. [AWS ElastiCache](./docs/redis.md#aws-elasticache) |
| AWS ElastiCache, cluster mode enabled (with or without IAM) | Your own `Cluster` in custom handler files. [Redis Cluster](./docs/redis.md#redis-cluster), [IAM on your own client](./docs/redis.md#iam-on-your-own-client) |
| Your own client (Sentinel, other ioredis options or timeouts) | [Custom handlers](./docs/custom-handlers.md) |
| Upgrading from 16.4.2 | [Migrating](./docs/migrating.md) |

Then keep writing `"use cache"`, `cacheTag` and `revalidateTag` as Next documents them
([examples](./docs/usage.md)).

**Setting it up with a coding agent?** Paste the prompt in [docs/agent-setup.md](./docs/agent-setup.md)
into Claude Code, Cursor or similar.

The package version follows Next.js. A range such as `^16.4.3` would also accept the 16.5
releases, which remove the APIs deprecated in 16.4.3, so pin it and upgrade the two together
([why](./docs/installation.md#install)). `ioredis` is installed with the package as an optional
dependency ([unless optionals are skipped](./docs/installation.md#install)).

## What you get

- **Pages and route handlers** (and cached `fetch`) stored in Redis, shared by every instance.
Prerendered pages are served from the build output after a restart.
- **Storage by directive.** `"use cache: remote"` entries live in Redis, shared by every
instance; plain `"use cache"` defaults to each instance's memory, with tag invalidation shared
through Redis. `"use cache: private"` is Next's own and never reaches a handler. Set
`useCache: "redis"` to share plain `"use cache"` values too. Next's deprecated
`experimental.useCache` flag works as well as
`cacheComponents`.
- **Next's directives, one to one.** `"use cache: remote"` entries live in Redis, shared by every
instance. Plain `"use cache"` stays in each instance's memory, with tag invalidation shared
through Redis; set `useCache: "redis"` to share it too. `"use cache: private"` is Next's own and
never reaches a handler.
- **Revalidation across instances.** `revalidateTag`, `updateTag` and `revalidatePath` reach
every instance and every handler, including each instance's in-memory `"use cache"` values.
every instance and every handler.
- **Redis outage safety.** A request never fails because of the cache. Commands time out after
1 s, and while Redis is down the app serves from per-instance memory, then goes back to Redis.
1 s, and while Redis is down the app serves from per-instance memory.
- **Entries scoped by build**, so a deploy never serves the previous build's pages.
- **`next build` never connects to Redis.**

[How it works](./docs/how-it-works.md) has the details: what goes where, tag coordination, page
lifetimes and the outage table.
[How it works](./docs/how-it-works.md) has the details.

## Configuration

### `withCache(nextConfig, options?)`
Runtime settings come from the environment of the running app. The main variables:

These options are read when `next.config` loads. Runtime settings come from the environment, except `memory`.
| Variable | Meaning |
|---|---|
| `REDIS_URL` (or `VALKEY_URL`) | `redis://` or `rediss://` URL. Unset → memory only. |
| `ELASTICACHE_ENDPOINT`, `ELASTICACHE_AUTH_TOKEN` | ElastiCache host form, TLS on. For IAM, see [IAM authentication](./docs/redis.md#iam-authentication). |
| `CACHE_KEY_PREFIX` | Prefix for every key (default `nextjs:`). |
| `CACHE_REDIS=off` | Memory everywhere, even with a URL set. |
| `CACHE_DEBUG=1` | Log hits, misses, writes and state changes. |

The [installation guide](./docs/installation.md#environment-variables) has the full table. There
are no variables for timeouts or TTLs; for those, or your own client, see
[Custom handlers](./docs/custom-handlers.md).

`withCache(nextConfig, options?)` takes three options:

| Option | Default | What it does |
|---|---|---|
| `pages` | `true` | Set `cacheHandler` (pages, route handlers, cached `fetch`) and `cacheMaxMemorySize: 0`. A `cacheMaxMemorySize` you set yourself is kept, with a warning if it is not `0`. `false` leaves `cacheHandler` and `cacheMaxMemorySize` as your config has them. |
| `useCache` | `"memory"` | `"redis"` stores plain `"use cache"` values in Redis too. Each read checks Redis; fresh instances of the same build reuse existing values. `handlers.default` overrides this choice. `handlers.remote` only changes `"use cache: remote"`. |
| `pages` | `true` | Also handle pages, route handlers and cached `fetch` (`cacheHandler`). `false` leaves them to Next. |
| `useCache` | `"memory"` | `"redis"` stores plain `"use cache"` values in Redis too, so instances of the same build share them. `handlers.default` overrides it. |
| `handlers` | built-in files | `{ page?, default?, remote? }`: paths to [your own handler files](./docs/custom-handlers.md). |
| `memory` | `{ heapPercent: 10 }` | The in-process cache budget per runtime: `heapPercent` of V8's heap limit (a little above `--max-old-space-size`), or `maxMiB` (an absolute budget, which wins). Wins over the `CACHE_MEMORY_*` variables. Not seen by a standalone `server.js`, which never loads `next.config`: use the variables there. See [Memory](./docs/operations.md#memory). |

```js
// Share plain "use cache" values across instances (REDIS_URL required)
export default withCache({ cacheComponents: true }, { useCache: "redis" });
```

```js
// "use cache" only; leave pages to Next's default cache
export default withCache({ cacheComponents: true }, { pages: false });
```
| `memory` | `{ heapPercent: 10 }` | The in-process cache budget. Not seen by a standalone `server.js`: use the `CACHE_MEMORY_*` variables there. See [Memory](./docs/operations.md#memory). |

`withCache` throws if the config already sets `cacheHandlers`, or `cacheHandler` unless
`pages: false`, because two configs fighting over the cache is always a bug. Use `handlers`
instead. It also accepts a function-form `next.config`.

### Environment variables

| Variable | Default | Meaning |
|---|---|---|
| `REDIS_URL` (or `VALKEY_URL`) | unset → memory only | `redis://` or `rediss://` URL, password included. |
| `REDIS_PASSWORD` | — | Password when the URL has none. |
| `ELASTICACHE_ENDPOINT`, `ELASTICACHE_PORT`, `ELASTICACHE_AUTH_TOKEN`, `ELASTICACHE_TLS` | port `6379`, TLS on | Host form, used when no URL is set. `ELASTICACHE_TLS=false` turns TLS off. |
| `ELASTICACHE_IAM_USER` | unset | ElastiCache IAM authentication as this user id, instead of an auth token, with tokens refreshed by the package ([details](./docs/redis.md#iam-authentication)). Needs TLS. |
| `ELASTICACHE_CACHE_NAME` | — | With IAM: the replication group id or serverless cache name the token is signed for. Required. |
| `ELASTICACHE_REGION` | `AWS_REGION`, then `AWS_DEFAULT_REGION` | With IAM: the cache's region. |
| `ELASTICACHE_SERVERLESS` | from the hostname | With IAM: `true` for ElastiCache Serverless; unset, on for a `.serverless.` endpoint. |
| `CACHE_KEY_PREFIX` | `nextjs:` | Prefix for every key. Use it to share one Redis between apps. |
| `CACHE_REDIS` | `on` | `off` forces memory everywhere, even with a URL set. |
| `CACHE_DEBUG` | unset | `1` logs hits, misses, writes and state changes. It never logs the URL. |
| `CACHE_COMPRESSION` | `on` | Entries of 16 KB and more are Brotli-compressed. `off` stores them uncompressed. |
| `CACHE_MEMORY_HEAP_PERCENT` | `10` | In-process cache budget as a share of the V8 heap limit, in percent (more than 0, less than 100). |
| `CACHE_MEMORY_MAX_MIB` | unset | In-process cache budget in MiB. Wins over `CACHE_MEMORY_HEAP_PERCENT`. `withCache`'s `memory` wins over both. |

There are no tuning variables for timeouts or TTLs. The [installation guide](./docs/installation.md#environment-variables)
has the full table; for your own client or timeouts, see [Custom handlers](./docs/custom-handlers.md).

## Tested against Next.js's own tests

Every PR that changes the package's source runs the caching e2e suites from the
[`vercel/next.js`](https://github.com/vercel/next.js) repo, using Next's deploy-mode test harness
for deployment adapters. Each suite runs twice: once against a plain `next start`, and once with
this package, two instances behind a round-robin proxy (one instance where a fixture keeps its own
handler), sharing one Redis. CI fails if a suite (or a test) that passes on `next start` does not
pass with the package.

At Next 16.4.2 that is **0 regressions outside one known Next bug**: apart from `app-static`
(below), every suite and test that passes on `next start` also passes with the package. 28
suites, 18 of which run tests in deploy mode
([results](./tests/next-deploy/results/baseline-v16.4.2.md); live results on the
[deploy-tests workflow](https://github.com/mrjasonroy/cache-components-cache-handler/actions/workflows/next-deploy-tests.yml)).
The limits:

- `test/e2e/app-dir/app-static` fails with any custom cache handler, because of a Next bug
(Turbopack's edge `cacheHandlers` registration, fixed in a later Next canary,
vercel/next.js#100046). It is listed as a known failure.
- 10 suites, such as `use-cache` and `ppr-full`, run no tests in deploy mode, so they are not
covered here.

The package's own tests add an e2e matrix on production builds (memory, Redis, Valkey, and the
ElastiCache host form: Redis with TLS and an auth token), including two instances sharing Redis
and Redis stopped mid-run, and an outage suite on real Redis 7 and Valkey 8 (down at boot, lost
mid-run, stalled, back).

ElastiCache IAM authentication is tested against a real ElastiCache Serverless cache (Valkey 8.1):
connecting with a token, re-authenticating the live connection, reconnecting, a tag revalidation
across two connections and `flushCache`. That needs an AWS account and a runner in the cache's
VPC, so it is not in per-PR CI: it is a manual gate before a release
(`scripts/aws-iam-e2e/run.sh`, see [development](./docs/development.md#elasticache-iam-against-a-real-cache)).
The token signing and refresh are unit-tested on every PR.
See [the harness README](./tests/next-deploy/README.md) and
[how it's tested](./docs/development.md#how-its-tested).

## Supported backends

| Backend | How |
|---|---|
| **Memory** | No `REDIS_URL`: dev, CI, previews, single instance |
| **Redis 6.2+** | `REDIS_URL=redis://…` or `rediss://…` |
| **Valkey** | `VALKEY_URL` or `REDIS_URL`, same URL format |
| **AWS ElastiCache** | `ELASTICACHE_ENDPOINT` + `ELASTICACHE_AUTH_TOKEN`, TLS on (`ELASTICACHE_TLS=false` turns it off) |
| **AWS ElastiCache, IAM auth** | `ELASTICACHE_ENDPOINT` (or a `rediss://` `REDIS_URL`) + `ELASTICACHE_IAM_USER`, `ELASTICACHE_CACHE_NAME`, `ELASTICACHE_REGION`. TLS required; Valkey 7.2+ or Redis OSS 7.0+; node-based or serverless (detected from a `.serverless.` endpoint, or `ELASTICACHE_SERVERLESS`). Needs the optional peer dependencies `@smithy/signature-v4`, `@aws-crypto/sha256-js` and `@aws-sdk/credential-provider-node`. [Details](./docs/redis.md#iam-authentication) |
| **Redis Cluster, Sentinel** | Your own ioredis client through a [custom handler](./docs/custom-handlers.md). `flushCache` scans every master. |

The minimum is Redis 6.2 (or any Valkey): revalidations use `ZADD GT` and a single-key Lua
script, so the server must allow `EVAL`/`EVALSHA`. CI runs Redis 7 and Valkey 8.
[Redis Configuration](./docs/redis.md) covers connections, key layout and sizing.

## Migrating

From 16.4.2, replace your handler files and `cacheHandlers` config with
`withCache({ cacheComponents: true })` and delete the files. `"use cache"` then goes to memory and
`"use cache: remote"` to Redis (or set `useCache: "redis"` to share plain `"use cache"` too), and
pages go through Redis too. The cache starts cold, and
revalidations do not cross between 16.4.2 and 16.4.3 instances during a rolling deploy: deploy
with recreate, or revalidate once afterwards. `RedisCacheHandler` subclasses keep working.

From `@fortedigital/nextjs-cache-handler` or `@neshca/cache-handler`, replace `cacheHandler` and
`cacheMaxMemorySize` with `withCache`.

The [migration guide](./docs/migrating.md) has the details.
`pages: false`. Use `handlers` instead. The [API reference](./docs/api-reference.md#withcachenextconfig-options)
has the details.

## Requirements and testing

Redis 6.2+ or any Valkey, with Lua scripting allowed (revalidations use `ZADD GT` and a
single-key script). CI runs Redis 7 and Valkey 8, a production-build e2e matrix (memory, Redis,
Valkey, ElastiCache with TLS and an auth token) and an outage suite. Every PR that changes the
package also runs Next.js's own caching e2e suites, with two instances sharing Redis, and fails
on any regression against plain `next start`. ElastiCache IAM is tested by hand against a real
ElastiCache Serverless cache before each release.
[How it's tested](./docs/development.md#how-its-tested) has the details and known limits.

## Documentation

Expand Down
Loading
Loading