# Migration Guide: Cache Handler

This guide covers adding the cache handler that new projects from `create-p1-starter-kit` have. When the editor revalidates a page after Go live, the handler purges the CDN in front of the site on Pantheon hosting, so visitors see the new page without waiting for the cache to expire. Anywhere else it falls back to a file cache. It needs `@pantheon-systems/p1-next-sdk@0.15.0` or newer: before that, Go live does not revalidate the page.

New projects already have this. This guide is only for **existing projects**.

> **Nothing fails if you skip this.** A project without the handler keeps rendering. A page that goes live is revalidated by Next.js, but the CDN keeps serving its previous copy until that copy expires.

## Requirements

- Node.js 22 or newer.
- `next` `>=15.5.28 <17`. This is the handler's own peer range; the codemod stops, saying so, when the installed version is outside it.
- `@pantheon-systems/p1-next-sdk` 0.15.0 or newer. The codemod warns, without stopping, when the installed packages are older.

## Recommended: run the codemod

From your project root, on a clean git tree:

```bash
npx @pantheon-systems/p1-next-sdk migrate cache-handler --dry-run   # preview
npx @pantheon-systems/p1-next-sdk migrate cache-handler             # apply
```

Then install the new dependency with the command it prints (`npm install`, `pnpm install` or `yarn install`).

It makes four changes, each checked on its own so a second run changes nothing:

1. Adds `"@pantheon-systems/nextjs-cache-handler": "^0.14.0"` to `dependencies` in `package.json`, keeping the file's formatting. A range you already declare in `dependencies` is kept.
2. Writes `cacheHandler.mjs` at the project root.
3. Adds `/.cache/` to `.gitignore`, after `/.next/` when there is one. The handler writes build metadata there; its file cache is mostly under `.next/cache/`, which is already ignored. A project with no `.gitignore` gets a warning instead of a new file.
4. Adds the cache options to `next.config.mjs`.

It refuses to run on a dirty tree unless you pass `--force`, and it plans every file before writing any. It bails, leaving the tree untouched, when it cannot make a change safely. These bails point back to this guide:

- `next.config.mjs` differs from a config the starter shipped, since it edits the file only when it matches one. The oldest shipped version does not import `createRequire`, and the codemod adds that import.
- `next.config.mjs` already sets a different `cacheHandler`.
- The project is configured in `next.config.js`, `next.config.cjs`, `next.config.ts` or `next.config.mts`.
- `cacheHandler.mjs` already exists with different contents.
- `next.config.mjs` points `cacheHandler` at `./cacheHandler.mjs` but does not set `cacheMaxMemorySize: 0`.
- `next.config.mjs` matches a config the starter shipped, but the options could not be added to it.
- There is no `next.config.mjs` in the directory.
- `package.json` is not in a shape it can edit safely.

If one of those bails, follow the manual steps below.

These bails say what to change and do not point here:

- `@pantheon-systems/nextjs-cache-handler` is declared only in `devDependencies` or `optionalDependencies`. `cacheHandler.mjs` imports it at runtime, so a production install that skips those sections breaks the app. Move it to `dependencies`, then re-run.
- The installed `next` is outside the range above. Upgrade `next`, reinstall, then re-run.
- There is no `package.json` in the directory. Run it from your project root.

## Manual steps

### 1. Add the dependency

```bash
npm install @pantheon-systems/nextjs-cache-handler@^0.14.0
```

### 2. Add the handler

`cacheHandler.mjs`:

```js
import { createCacheHandler } from "@pantheon-systems/nextjs-cache-handler";

export default createCacheHandler({ type: "auto" });
```

`type: "auto"` purges the CDN on Pantheon hosting and uses a file cache elsewhere.

### 3. Point Next.js at it

In your Next.js config, add both options. If your config is a `.ts` or `.js` file, put them in that file; the handler's path has to be absolute, so resolve it:

```js
import { createRequire } from "module";
const require = createRequire(import.meta.url);

export default {
  reactStrictMode: true,
  cacheHandler: require.resolve("./cacheHandler.mjs"),
  cacheMaxMemorySize: 0,
  // …the rest of your config
};
```

`cacheMaxMemorySize: 0` turns off Next.js's in-memory cache, which would otherwise answer before the handler is asked. Do not add `@pantheon-systems/nextjs-cache-handler` to `transpilePackages`: it breaks the handler's edge-runtime entry.

If you already have a `cacheHandler`, either keep it and skip this guide, or replace it with the one above.

### 4. Ignore the file cache

Add `/.cache/` to `.gitignore`. The handler writes build metadata there.

## Removing the handler on hosts other than Pantheon

Off Pantheon hosting the handler only keeps a file cache, mostly under `.next/cache/`, which is the same behavior Next.js gives you without it. To remove it:

1. Delete the `cacheHandler` and `cacheMaxMemorySize` lines from your Next.js config.
2. Delete `cacheHandler.mjs`.
3. Uninstall the dependency: `npm uninstall @pantheon-systems/nextjs-cache-handler`.
4. Optionally remove `/.cache/` from `.gitignore`.

## Check the result

- `next build` and `next start` run without a cache-handler error.
- On Pantheon hosting, a page you take live shows its new content on the next visit, without waiting for the cache to expire.
