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.
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.
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 # previewnpx @pantheon-systems/p1-next-sdk migrate # apply
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.
When you're done with everything, run pnpm install, pnpm typecheck and pnpm test, and fix anything they report.
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.
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: