# Prisma Prisma Next Prisma Next

> Upgrade Prisma Next (extension)

- Skill: `tomevault-io/prisma-prisma-next-prisma-next` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/prisma-prisma-next-prisma-next`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/prisma-prisma-next-prisma-next/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/prisma-prisma-next-prisma-next

---


# 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` or `@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` or `peerDependencies`, and
- the package's `name` matches `^@.*/extension-` (the in-tree convention used by `@prisma-next/extension-pgvector`, 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:

1. **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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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.

7. **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.

---
> Source: [prisma/prisma-next](https://github.com/prisma/prisma-next) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-07-02 -->