docs: add Prisma Next Middleware and Extensions sections

[sorenbs]

What this PR does

Adds the Middleware and Extensions sections to the Prisma Next ORM docs at /docs/orm/next, per the middleware + extensions Linear tickets and section 5 of prisma-next-user-docs-spec.md. The goal for this round is accuracy and crawlability: every package name, import path, option default, and error code was verified against the prisma/prisma-next source at v0.14.0.

New pages

Middleware (/docs/orm/next/middleware/*, new section, 5 pages)

• How middleware works: the hook model (beforeCompile, beforeExecute, intercept, onRow, afterExecute), the lifecycle, registration order semantics, what ships built in, error behavior, and family compatibility.
• Built-in: budgets: row-count and latency ceilings from @prisma-next/sql-runtime (BUDGET.ROWS_EXCEEDED, BUDGET.TIME_EXCEEDED), with the three enforcement checkpoints and defaults.
• Built-in: lints: structural query checks (LINT.DELETE_WITHOUT_WHERE, LINT.UPDATE_WITHOUT_WHERE, LINT.NO_LIMIT, LINT.SELECT_STAR), severity configuration, and the raw-SQL fallback heuristics.
• Built-in: cache: opt-in per-query caching from @prisma-next/middleware-cache via cacheAnnotation({ ttl }), key derivation, scope behavior, and hit observability.
• Authoring custom middleware: a complete slow-query-warning middleware (implemented and unit-tested in prisma/prisma-next examples/prisma-next-demo, see the companion PR there), the full hook/context reference, a beforeCompile query-rewriting variation, and gotchas.

Extensions (/docs/orm/next/extensions/*, new section, 1 page)

• Using extensions: end-to-end pgvector setup (install, /control registration in prisma-next.config.ts, /runtime registration on the client, contract types, baseline migrations running CREATE EXTENSION), a capabilities explainer, and the catalog table (pgvector, PostGIS, ParadeDB, Supabase, arktype-json) with honest maturity notes and a link to the call for extension authors.

Both sections are wired into the sidebar via orm/next/meta.json. "Middleware" is used throughout; the retired "plugin" term does not appear (verified it is also gone from the product's public API).

Notes and deliberate deviations

• "Built-in: telemetry" is not written. The docs spec lists it (via @prisma-next/middleware-telemetry), but no telemetry middleware package exists in the product today; the only telemetry surface is the runtime.telemetry() accessor, which is not middleware. The built-in that actually ships from a separate package is the cache, documented instead. Flagging so the spec owner can reconcile.
• No redirect from /docs/orm/prisma-client/client-extensions. That URL (and children) still serves live Prisma 7 GA content; redirecting it to the Next section now would remove reachable docs. It maps cleanly to /docs/orm/next/extensions/using-extensions when the broader IA/redirect work (DR-8687) lands. /docs/orm/prisma-schema/postgresql-extensions is likewise left in place, flagged for SEO review (different concept now).
• Middleware needs no v7 redirects: no old middleware/$use pages exist in the current docs (confirmed by search).
• Cross-links: the per-extension "guide" links point at the GitHub package READMEs until the Guides section (DR-8689) exists, and capability detail is prose until the Capabilities page (DR-8680) exists. Swap those links when the sections land.
• The pages first landed under /docs/next/* and were moved to /docs/orm/next/* in a follow-up commit on this branch; the previously flagged (index)/meta.json conflict with feat/prisma-next-reference no longer applies (this branch no longer touches that file).

Validation

• pnpm --filter docs run lint:links — 0 errors
• pnpm --filter docs run lint:spellcheck — 0 issues (added paradedb to the dictionary)
• pnpm --filter docs run types:check
• All runtime examples verified against prisma/prisma-next v0.14.0 source; the authoring example is committed and tested in the companion prisma-next PR

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added new ORM Next Middleware docs, including how middleware works, how to author custom middleware, and reference guides for built-in cache, budgets, and lints.
  • Added new ORM Next Extensions docs, including installation/registration instructions, capability requirements, and a first-party extensions catalog (e.g., pgvector, PostGIS, ParadeDB, Supabase, arktype-json).
  • Updated ORM Next documentation navigation to include the new Middleware and Extensions sections.
• Chores
  • Updated spell-check terms to include “paradedb”.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
blog	Ready	Preview, Comment	Jul 7, 2026 10:52am
docs	Ready	Preview, Comment	Jul 7, 2026 10:52am
eclipse	Ready	Preview, Comment	Jul 7, 2026 10:52am
site	Ready	Preview, Comment	Jul 7, 2026 10:52am

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

This PR adds Prisma Next docs for middleware and extensions, plus navigation metadata and a cspell entry.

Changes

Middleware and Extensions Documentation

Layer / File(s)	Summary
Docs navigation wiring apps/docs/content/docs/orm/next/meta.json, apps/docs/content/docs/orm/next/extensions/meta.json, apps/docs/content/docs/orm/next/middleware/meta.json	Registers the Middleware and Extensions sections and their page entries in the Prisma Next docs navigation.
Authoring custom middleware guide apps/docs/content/docs/orm/next/middleware/authoring-custom-middleware.mdx	Adds a slowQueryWarning example and documents hook behavior, AST rewriting, short-circuiting, cross-family use, and gotchas.
Built-in budgets middleware page apps/docs/content/docs/orm/next/middleware/built-in-budgets.mdx	Documents budgets registration, configuration, enforcement points, error shapes, and mitigation guidance.
Built-in lints and cache middleware pages apps/docs/content/docs/orm/next/middleware/built-in-lints.mdx, apps/docs/content/docs/orm/next/middleware/built-in-cache.mdx	Documents lint rules, severities, raw-SQL fallback, and cache annotations, cache keys, runtime scope, and options.
Extensions documentation apps/docs/content/docs/orm/next/extensions/using-extensions.mdx, apps/docs/cspell.json	Describes extension installation, control/runtime registration, capabilities, supported extensions, related links, and adds paradedb to spellcheck.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• prisma/web#7999: Also updates the Prisma Next docs navigation and related docs surface.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding Prisma Next Middleware and Extensions docs sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🍈 Lychee Link Check Report

37 links: ✅ 10 OK | 🚫 0 errors | 🔀 0 redirects | 👻 27 excluded

✅ All links are working!

---

Full Statistics Table

Status	Count
✅ Successful	10
🔀 Redirected	0
👻 Excluded	27
🚫 Errors	0
⛔ Unsupported	0
⏳ Timeouts	0
❓ Unknown	0

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Jul 7, 2026, 10:59 AM

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/docs/content/docs/`(index)/next/extensions/using-extensions.mdx:
- Around line 83-93: The extension table links currently point to GitHub package
directories rather than documentation guides, so clarify the destination or
change the targets. Update the table rows in using-extensions.mdx and the
surrounding copy so readers understand these links leave the docs site, or
retarget them to the actual guide pages if those exist.

In
`@apps/docs/content/docs/`(index)/next/middleware/authoring-custom-middleware.mdx:
- Around line 47-60: The middleware registration order in the db runtime setup
is wrong: `budgets()` is placed before `slowQueryWarning()`, so `afterExecute`
can throw before the custom warning runs. Update the `postgres<Contract>`
configuration in the `db` setup so `slowQueryWarning({ thresholdMs: 250 })` is
registered before `budgets()` in the `middleware` array, while keeping `lints()`
first with the built-ins.

In `@apps/docs/content/docs/`(index)/next/middleware/built-in-cache.mdx:
- Around line 54-65: The ORM example currently creates orm with an empty
collections object, which leaves models.public without a User binding and makes
models.User.first unusable. Update the snippet to pass the generated collection
bindings into orm via the collections option, or change the example to use the
higher-level db.orm.User API if that is the intended flow; reference orm,
collections, models.public, and models.User.first to keep the fix aligned with
the existing snippet.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b5064920-c168-40b9-a0a3-619a1b43ef4c

📥 Commits

Reviewing files that changed from the base of the PR and between d406817 and 612f6b4.

📒 Files selected for processing (10)

• apps/docs/content/docs/(index)/meta.json
• apps/docs/content/docs/(index)/next/extensions/meta.json
• apps/docs/content/docs/(index)/next/extensions/using-extensions.mdx
• apps/docs/content/docs/(index)/next/middleware/authoring-custom-middleware.mdx
• apps/docs/content/docs/(index)/next/middleware/built-in-budgets.mdx
• apps/docs/content/docs/(index)/next/middleware/built-in-cache.mdx
• apps/docs/content/docs/(index)/next/middleware/built-in-lints.mdx
• apps/docs/content/docs/(index)/next/middleware/how-middleware-works.mdx
• apps/docs/content/docs/(index)/next/middleware/meta.json
• apps/docs/cspell.json

[ankur-arch]

Ran the middleware examples against @prisma-next 0.14.0 on a live Postgres database (create-db) before reviewing, since these pages make strong behavioral claims. Everything substantive checks out:

• lints() blocks DELETE without WHERE (DELETE without WHERE clause blocks execution...) and lets an unbounded SELECT run with a warning, as documented.
• budgets({ maxRows: 2 }) rejects an unbounded SELECT before the driver runs; a bounded query within budget passes.
• createCacheMiddleware + cacheAnnotation({ ttl }) on the SQL builder serves the second identical read with result.source === 'middleware', exactly as the cache page describes.
• A custom afterExecute middleware receives plan.sql, result.rowCount, result.latencyMs, and result.source, and ORM queries flow through the same chain.
• The ORM meta-callback opt-in works too (details inline).
• All five extension packages exist on npm at 0.14.0, and @default(uuid()) in the extensions schema example emits a valid contract.

The v0.14 honesty notes (severities.latency accepted but not read, unindexedPredicate never emitted) are a great touch. Two inline suggestions plus one optional consistency note below.

Optional: the Fundamentals pages (#8011) now end with a "Prompt your coding agent" section (copyable prompts referencing the scaffolded skills), and the docs-writer skill gained references/prisma-next.md codifying the shared conventions for the parallel section PRs, including keeping any Prisma 7 cutover redirects commented out in next.config.mjs until /orm/next becomes /orm. These sections are net new so no redirects apply, but the agent-prompt ending would fit these pages well.

[ankur-arch]

Pushed a revision (c33b786) applying the review feedback from this thread plus the session feedback on tone and teaching. Summary:

Animations

• The pipeline scene's geometry is fixed: every box in the chain now shares one vertical center, so the request lane is a straight line and the tall-box empty band that read as broken layout is gone. The return lane and the cache-hit shortcut run through a clear band inside the endpoint boxes.

• The dense text lifecycle line is now a stepped Code Hike animation (middleware-lifecycle), one concern per step. Designed from this Mermaid sketch:

  flowchart LR
    A[beforeCompile] --> L[SQL lowering] --> B[beforeExecute] --> E[param encoding] --> I[intercept] --> D[(driver)] --> R[onRow, per row] --> F[afterExecute]
    I -. cached rows, driver skipped .-> F
  

  Loading

Writing

• how-middleware-works opens with what you can do in plain words, and the five-hook table is now five short subsections with a micro example where it helps.
• "Runtime family" is explained in plain language: SQL family vs document family, and what familyId buys you (a startup error instead of a production query error).
• authoring-custom-middleware is rewritten as a numbered hand-holdy guide in the house guide style: build a query logger, register it, run a query, see the output, then add a threshold option. The terminal output shown is captured from a live run against 0.14.0.

Validated fixes

• The cache page's ORM opt-in now uses the facade path, verified with a cache hit on the second call:
  db.orm.public.User.first({ id }, (meta) => meta.annotate(cacheAnnotation({ ttl: 60_000 }))). This also resolves CodeRabbit's collections: {} finding and removes the db.connect() already-connected footgun.
• Registration-order note added (logger before budgets), per CodeRabbit.
• One finding from testing: ctx.log events are invisible today because postgres(...) accepts no log sink and does not forward one to the runtime. The authoring guide says so and logs via its own logger; the lints page notes that warn severities are therefore not observable yet, while error severities still block (verified: lints() blocks DELETE without WHERE, budgets({ maxRows }) blocks an unbounded SELECT).
• Extension catalog links relabeled README and described as GitHub links, per CodeRabbit.

Validation: types:check clean, cspell 0 issues, both animations confirmed rendering (new viewBox present, lifecycle preset server-rendered). A heads-up for merge order: this branch and #8011 both touch concept-animation/flow-presets.ts, presets.ts, and index.tsx, so whichever lands second gets a small conflict; the index.tsx lookup fix here matches the shape #8011 uses.

[ankur-arch]

Re-validated 2026-07-07 on a fresh Prisma Postgres database: lints blocks DELETE without WHERE, budgets blocks an unbounded SELECT and passes a bounded one, the cache serves the second annotated read with source 'middleware' through both the SQL-builder and the facade ORM path, and the authoring guide's query logger produces the exact output shown on the page. Also verified the family-agnostic claim on a local MongoDB replica set: createCacheMiddleware registers on the mongo client without a family mismatch and queries run through it.

[ankur-arch]

Pushed 7357f84 addressing the diagram and guide feedback.

Diagrams: redesigned from minimal Mermaid sketches, then rebuilt as small flow scenes with one-sentence captions.

The pipeline is now three boxes and one idea:

flowchart LR
  app[Your app] --> mw["Middleware (cache · lints · budgets)"] --> db[(Database)]
  mw -. cached rows .-> app

Loading

Steps: pass through, block (the arrow into the database disappears), answer from cache (dashed return, database skipped), observe results.

The lifecycle replaces the eight-row text table with just the five hooks in order:

flowchart LR
  bc[beforeCompile<br/>rewrite] --> be[beforeExecute<br/>guard] --> ic[intercept<br/>answer early]
  ic -- driver --> orow[onRow<br/>each row] --> ae[afterExecute<br/>observe]

Loading

The extensions diagram is four plain boxes, and it now comes after a concrete five-step example (install, register in config, register on client, use the type in the schema, apply and query):

flowchart LR
  pkg[extension package] --> cfg[prisma-next.config.ts] -- db init --> pg[(PostgreSQL)]
  pkg --> rt[db.ts] -- queries --> pg

Loading

Wording: the Capabilities section is rewritten in plain language (the keys exist so failure happens at client construction and at db init, never mid-query), and the catalog table drops the Status column and the long feature prose; extension names link to the READMEs and one line covers maturity.

Authoring guide, proven end to end: re-ran the whole guide on a fresh create-prisma project against a live Prisma Postgres database and rewrote it to mirror that run exactly: complete listings of both files the reader touches, the real two-line logger output (INSERT and SELECT with latency), a what-to-check line if no output appears, and the tested threshold behavior (logger goes quiet at 250ms). Family selection is folded in as step 5 in plain words.

Validation: types clean, cspell clean. The concept-animation typing change here matches #8011's shape so the eventual merge stays trivial.

[ankur-arch]

Synced with main now that Fundamentals (#8011) is merged: the concept-animation conflict is resolved by combining both scene sets (the relationship diagrams from Fundamentals plus the simplified middleware, lifecycle, and extensions scenes from this PR) in one registry, and the sidebar orders Fundamentals before Middleware and Extensions. Added cross-links into the now-merged Fundamentals section (writing-data from the middleware overview, advanced-queries from the extensions page); the budgets page's pagination link now resolves too. Types clean, link check 0 errors. Merge-ready.