prisma-next-upgrade

---
name: prisma-next-upgrade
description: >-
  Upgrade Prisma Next in your app. Bumps every `@prisma-next/*` dependency
  from the version pinned in the lockfile to the requested target (or npm
  `latest`), applies any required code-translation steps from the
  per-transition upgrade instructions, validates with the project's own
  typecheck + tests, and commits each minor step on its own. Use when the
  user asks to "upgrade Prisma Next", "bump Prisma Next", "move to Prisma
  Next X.Y", or asks an agent to deal with an `@prisma-next/*` minor bump
  in their app.
---

# Upgrade Prisma Next (user app)

This skill upgrades a project that **consumes** Prisma Next via the public package API (`@prisma-next/postgres`, `@prisma-next/mongo`, the contract files in `prisma/`, etc.). If the project is itself a Prisma Next *extension*, use the `prisma-next-extension-upgrade` skill instead — or both, if the repo contains both an app and an extension package.

## Step 0 — Ensure the skill is up to date

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

If the agent runtime supports an in-session refresh, perform it now. Otherwise, exit and ask the user to re-install (`pnpm dlx skills add prisma/prisma-next/skills/upgrade --all`), then re-invoke. The upgrade-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.

## Pre-flight — extension compatibility

Before changing any code, refuse to upgrade past any installed extension's pinned Prisma Next version. Extensions in Prisma Next pin every `@prisma-next/*` dependency to a single exact version (no carets, no ranges); that pin is the highest version the extension has been validated against. Upgrading the user app past that pin would silently desynchronise the extension's type identity from the app's.

Steps:

1. **Read `prisma-next.config.ts`** (or its TS-discoverable equivalent at the project root) and enumerate the list of extension packages it imports. Each `extensions: [...]` entry corresponds to an installed npm package.
2. **For each extension**, read its installed `package.json` from `node_modules/<extension-package-name>/package.json` and find any `@prisma-next/*` entry under `dependencies`, `peerDependencies`, or `optionalDependencies`. By construction those entries are exact-version pins (e.g. `"0.7.0"`), set when the extension author last ran their own upgrade.
3. **Compute the lowest pinned version across all extensions.** That is the highest Prisma Next version reachable by this app on its current extension set.
4. **Compare to the user's target.** If the target exceeds the lowest pin, halt with a structured message naming each lagging extension and its pinned version, and offer two paths:
   - (a) Wait for the lagging extension to publish a compatible release, then re-run.
   - (b) Re-run with `--to=<highest-reachable>` (or whatever flag/option the user is using to set the target).

Do not auto-downgrade the target; do not skip the lagging extension; do not bump past it. If the user explicitly overrides the halt, surface the risk clearly first.

If `prisma-next.config.ts` is absent or names no extensions, skip the pre-flight.

## Role detection

This skill applies when the project **consumes** Prisma Next:

- `package.json` declares one or more `@prisma-next/*` packages under `dependencies` / `devDependencies`, and
- the package is *not* itself an extension (no `@prisma-next/contract` (or other SPI) under `dependencies`/`peerDependencies`; name does not match `^@.*/extension-`; not referenced from a sibling app's `prisma-next.config.ts`).

If the project also matches the extension-author role, install the `prisma-next-extension-upgrade` skill (`pnpm dlx skills add prisma/prisma-next/skills/extension-author --all`) and run **this** flow first, then that one in the same session. If detection is ambiguous, ask the user.

## 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/*` package. If the lockfile shows multiple `@prisma-next/*` packages at different minors (already broken), the **lowest** minor is the from-version.
- **To-version.** Either the version the user specified, or the latest stable from `npm view @prisma-next/postgres 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, validate, commit — before moving to the next. Halt the chain on the first failed step; do not skip ahead.

The chain order does not depend on which extensions are installed; the pre-flight has already established the target is reachable.

## Per-step flow

For each `(from, to)` step in the chain:

1. **Bump `@prisma-next/*` deps.** Rewrite every `@prisma-next/*` entry in the project's `package.json` to the exact `<to>` version (no caret, no tilde). All entries advance to the same version. Cover `dependencies` and `devDependencies`. The upgrade skill itself is delivered through `pnpm dlx skills add` and lives under `.agents/skills/prisma-next-upgrade/` (or the equivalent CLI-managed directory) — there is no `@prisma-next/upgrade-skill` npm entry to bump.

2. **Install.** Run `pnpm install` (or the project's lockfile-managing command). The project's code is now broken against the new types — the upgrade instructions for `<from> → <to>` exist to fix it.

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

4. **Apply each change.** For each entry in `changes[]`:
   - If the entry has a `detection` block (glob + content predicate), run it; skip the change if no files match. No `detection` → apply unconditionally.
   - If the entry names a `script:` (relative path next to `instructions.md`), invoke it from the project root: `*.ts` via `pnpm exec tsx <path>`, `*.sh` via `bash <path>`, codemods per the script's own prose. No `script` → follow the prose body directly.

   Empty `changes[]` (placeholder shape for transitions with no user-side breaking changes) is a no-op — proceed to validation.

5. **Validate.** Run `pnpm typecheck && pnpm test` (or the project's equivalent — the `scripts` field of the project'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.

6. **Commit.** One commit per step containing the `package.json` bump, lockfile churn, and any source rewrites:

   ```text
   chore: upgrade @prisma-next/* to <to-version>
   ```

   (Or the project's own commit-message convention.) Never squash steps. The user may squash on merge; the in-flight history must be per-step so a failed step is bisectable.

Then move on to the next step.

## 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 (e.g. tests that were already red before the upgrade and still are).

## Failure surfaces

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

If a pre-flight halt fires, do not bump anything; the project is left unchanged.

From prisma/prisma-next at 55458c4, shown as plain text under its license: Apache-2.0 (permissive). The license text is in LICENSE.

• SKILL.md8.1 KB · 96770e2a6413
• README.md2.4 KB · c114ac37296f
• upgrades/
• 0.10-to-0.11/
• instructions.md1.9 KB · b8b930f43755
• 0.11-to-0.12/
• instructions.md22 KB · ed5a46dbbd4c
• re-emit-closed-mongo-contracts.ts7.0 KB · a58b2eeeabc6
• re-emit-domain-namespaced-contracts.ts6.3 KB · aaa67373b519
• re-emit-postgres-public-default.ts6.4 KB · 39d419e80ae0
• strip-migration-labels-hints.ts13 KB · 405e43eb274c
• 0.12-to-0.13/
• instructions.md17 KB · cbc7997ab74c
• re-emit-mti-variant-link-columns.ts7.9 KB · 126262179c96
• 0.13-to-0.14/
• instructions.md30 KB · 1b97e1bb7473
• migration-op-factories-to-methods.ts10 KB · 50eb9b4b3c2d
• uuid-preset-rename.ts1.3 KB · 3c792a22ceed
• 0.14-to-0.15/
• instructions.md21 KB · bb3a8a9c35de
• 0.15-to-0.16/
• instructions.md11 KB · fad2f573f127
• 0.16-to-0.17/
• instructions.md30 KB · bc2e2b9b6b6b
• strip-sha256-hash-prefixes.ts15 KB · 1d02707ff195
• 0.7-to-0.8/
• instructions.md183 B · 55ef2ca791b2
• 0.8-to-0.9/
• instructions.md2.8 KB · 4d02fe935617
• strip-inline-contracts.ts8.0 KB · 56047244523a
• 0.9-to-0.10/
• instructions.md5.5 KB · 2b8806301b2b
• stamp-storage-types-kind.ts13 KB · f9c6c709a93b

22 files, 240 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.