Upgrade Prisma Next (extension)

This skill upgrades a project that is a Prisma Next extension — a package that consumes the framework SPI (

@prisma-next/contract

@prisma-next/framework-components

@prisma-next/migration-tools

, etc.) and exposes contract / middleware / codec / migration surfaces that downstream apps install via

prisma-next.config.ts

If the project you are upgrading is a consumer app (it imports

@prisma-next/postgres

@prisma-next/mongo

from its application code), use the

prisma-next-upgrade

skill instead — or both, if the repo contains both a consumer app and an extension package, in which case run the user flow first then the extension flow in the same session.

Step 0 — Ensure the skill is up to date

Before doing anything else, ensure this skill is installed at

@latest

and reload it. Bug fixes to old per-transition upgrade instructions ship in the latest skill release as part of its cumulative set; running against a stale skill can apply a known-broken translation.

Concretely: if the agent runtime supports an in-session refresh, perform it now. Otherwise, exit and ask the user to re-install:

bash

pnpm dlx skills add prisma/prisma-next/skills/extension-author --all

The extension-author skill subpath is intentionally unpinned (always

main

) — the cumulative instruction set is the source of truth and the latest release fixes apply to every prior transition.

Then re-invoke this skill before proceeding.

Role detection

This skill applies when the project is a Prisma Next extension. Heuristics:

package.json

declares

@prisma-next/contract

(or another SPI package) under

dependencies

peerDependencies

, and

the package's
```
name
```
matches
```
^@.*/extension-
```
(the in-tree convention used by
```
@prisma-next/extension-cipherstash
```
, etc.), or
the package is referenced as an
```
extensionPacks
```
entry from a sibling app's
```
prisma-next.config.ts
```
in the same monorepo.

If the project additionally consumes Prisma Next from its own app code, install the

prisma-next-upgrade

skill (

pnpm dlx skills add prisma/prisma-next/skills/upgrade --all

) and run the user flow first, then this flow in the same session.

If detection is ambiguous, ask the user which role to operate under.

Version detection

From-version. Read the currently-installed Prisma Next version from
```
pnpm-lock.yaml
```
(or
```
package-lock.json
```
/
```
yarn.lock
```
) by inspecting the resolved version of any
```
@prisma-next/*
```
entry. If the lockfile shows multiple
```
@prisma-next/*
```
packages at different minors, the lowest minor is the from-version.
To-version. Either the version the user specified, or the latest stable from
```
npm view @prisma-next/contract dist-tags.latest
```
.

Report both back to the user before continuing.

Transition chain

If the from-to delta spans multiple minor versions (e.g.

0.6 → 0.8

), build the chain of one-minor steps:

text

0.6 → 0.7 → 0.8

Apply each step in order, fully: bump, install, run instructions, check pins, validate, commit — before moving to the next. Halt the chain on the first failed step.

Per-step flow

This flow assumes you are an external extension author — your extension lives in its own repo and consumes

@prisma-next/*

from npm. (Extensions inside the

prisma/prisma-next

monorepo itself are bumped via

pnpm bump-minor

scripts/set-version.ts

, which rewrites every

workspace:<X.Y.Z>

spec in lockstep with the root version; they do not run this skill.)

For each

(from, to)

step in the chain:

Bump
@prisma-next/*
deps. Rewrite every
```
@prisma-next/*
```
entry in the extension's
```
package.json
```
to the exact
```
<to>
```
version (e.g.
```
"0.8.0"
```
— no caret, no tilde, no range, no
```
workspace:
```
specifier; the exact-pin rule below details why). All entries advance to the same version. Cover whichever dep field(s) the extension uses today —
```
dependencies
```
and/or
```
peerDependencies
```
— and any
```
optionalDependencies
```
. The extension-upgrade skill itself ships via
```
pnpm dlx skills add
```
(see Step 0); there is no
```
@prisma-next/extension-upgrade-skill
```
npm entry to bump. The companion CLI tool is
```
@prisma-next/extension-author-tools
```
— leave its pin at the version the extension's CI is currently using; bumping it is independent of the framework upgrade and is normally a no-op.
Install. Run
```
pnpm install
```
(or the project's lockfile-managing command). The extension's source is now broken against the new SPI — the upgrade instructions for
```
<from> → <to>
```
exist to fix it.
Check pins. Run
```
pnpm exec prisma-next-check-pins
```
(shipped by
```
@prisma-next/extension-author-tools
```
). This sanity check asserts that every
```
@prisma-next/*
```
entry across
```
dependencies
```
,
```
peerDependencies
```
, and
```
optionalDependencies
```
is a single exact-version string and that all entries share the same version. If the check fails, the bump step did not rewrite every spec — fix the offending entries and re-run before proceeding.
Read the upgrade instructions. Load
```
upgrades/<from>-to-<to>/instructions.md
```
from this skill package. Parse the YAML frontmatter and pay particular attention to its
```
changes[]
```
array.
Apply each change. For each entry in
```
changes[]
```
:
- If the entry has a
```
detection
```
  block (a glob + content predicate), run it. If no files match, skip this change.
- If the entry has no
```
detection
```
  , apply unconditionally.
- If the entry names a
```
script:
```
  (a relative path next to
```
instructions.md
```
  ), invoke it from the project root:
  - *.ts
    →
    pnpm exec tsx <skill>/upgrades/<from>-to-<to>/<script>
  - *.sh
    →
    bash <skill>/upgrades/<from>-to-<to>/<script>
  - codemods → invoke per the script's own
    instructions.md
    prose.
- If the entry has no
```
script
```
  , follow the prose body in
```
instructions.md
```
  directly.
If
```
changes[]
```
is empty (the placeholder shape for transitions with no extension-side breaking changes), this sub-step is a no-op — proceed to validation.
Validate. Run
```
pnpm build && pnpm test
```
(or the project's equivalent — the
```
scripts
```
field of the extension's
```
package.json
```
is the discovery surface). If anything is red, halt the chain. Do not auto-roll-back; surface the failure to the user with the failing change's
```
id
```
(from the frontmatter), the file paths the change operated on, and the inferred remediation.
Commit. Create one commit containing this step's changes: the
```
package.json
```
bump, the lockfile churn from
```
pnpm install
```
, and any source-file rewrites from the applied changes. Use the message:
text
```
chore: upgrade @prisma-next/* to <to-version>
```
(Or the extension's own commit-message convention, if it has one.) One commit per step — never squash steps.

Move on to the next step. Repeat.

Exact-pin rule

Prisma Next extensions pin every

@prisma-next/*

dependency to a single exact version (no

, no

, no range, no wildcard, no

workspace:

specifier in the published

package.json

). All

@prisma-next/*

entries share the same version. The pin advances only after a successful upgrade run against the new minor.

prisma-next-check-pins

(shipped by

@prisma-next/extension-author-tools

— install with

pnpm add -D @prisma-next/extension-author-tools

) enforces the rule. Run it locally with:

bash

pnpm exec prisma-next-check-pins

Wire it into the extension's CI alongside the build/test step so an accidental range pin fails the PR before it lands.

When the chain is done

Report back to the user: the number of steps applied, the SHAs of the commits you made, and any open follow-ups.

Failure surfaces

When a step fails:

Surface a structured error with code
```
PN-UPGRADE-NNNN
```
, the failing change's
```
id
```
, the file paths the change touched (or the lockfile, or the pin check, or the validation command), and the inferred remediation.
Do not retry automatically.
Do not auto-roll-back the commit. The user can revert if they want a clean slate.

prisma-next-extension-upgrade

NPX Install

Tags

SKILL.md Content