Update P1 site to latest P1 client

How to move an existing P1 site to a newer version of the P1 client packages.

Please use the package manager your site already uses (examples below use pnpm; npm works with the same arguments).

P1 is three npm packages released together on the same version: @pantheon-systems/p1-next-sdk, @pantheon-systems/puck-css, and @pantheon-systems/css-client. There is no single upgrade command: you update the packages, then apply any code changes listed for the release.

Update the Packages

Install the latest version of all three packages.

pnpm add @pantheon-systems/p1-next-sdk@latest @pantheon-systems/puck-css@latest @pantheon-systems/css-client@latest

- Update all three even if your site imports only some of them. Mismatched versions break the editor.

- pnpm update / npm update won't move you to a new P1 minor version, so name the version or use @latest as above.

Migrate routes (sites coming from 0.7 or earlier only)

If your project has an app/p1/(editor)/ folder, skip this step.

Otherwise, from the project root, with a clean git tree and after updating the packages:

npx @pantheon-systems/p1-next-sdk migrate --dry-run   # preview
npx @pantheon-systems/p1-next-sdk migrate             # apply

Find what changed in the starter kit

We highly recommend that you have a coding agent (Claude Code, etc.) of your choice handle this step.

Updating the packages doesn't update the files the starter kit copied into your site. To see what changed in those files, create a copy of the old and new starter kits, then compare them.

1. Find your starting version in package.json, under "p1": { "templateVersion": ... }.

2. Outside your project, create both starter kits. Replace <your templateVersion> with your version:

mkdir -p ~/p1-compare/old ~/p1-compare/new && cd ~/p1-compare
(cd old && npx @pantheon-systems/create-p1-starter-kit@<your templateVersion> my-site --yes --no-install --no-git)
(cd new && npx @pantheon-systems/create-p1-starter-kit@latest my-site --yes --no-install --no-git --no-blocks)

3. Then, list what changed between versions:

git diff --no-index --stat old/my-site new/my-site

4. Make those same changes to your site. Here is a reference guide on the types of changes you will likely be making:

Difference	What to do
=> /dev/null (deleted)	Delete it from your site
Changed, and you never edited it	Copy the file from new/my-site
Changed, and you did edit it	Run git diff --no-index old/my-site/<file> new/my-site/<file> and make the same edits by hand
package.json	Match the new dependencies with pnpm add / pnpm remove

5. Set templateVersion to the version in new/my-site/package.json, then delete ~/p1-compare.

Note: Keep any block in puck.config.tsx that your pages still use, even if the new starter kit removed it.

When you're done with everything, run pnpm install, pnpm typecheck and pnpm test, and fix anything they report.