docs(guides): Prisma Next guides with a Guides version dropdown (DR-8689)#8022
docs(guides): Prisma Next guides with a Guides version dropdown (DR-8689)#8022ankur-arch wants to merge 1 commit into
Conversation
…DR-8689)
- Add a "Guides version" dropdown to the guides section, mirroring the
CLI pattern: /guides stays the Prisma 7 tree, /guides/next holds the
Prisma Next tree. version.ts, the version switcher, and the versioned
sidebar tree gain guides handling; the latest sidebar hides the next
tree and vice versa (verified via rendered anchors).
- First converted batch, every flow run end to end against live Prisma
Postgres databases before writing: Bun (scaffold, emit, db init,
first typed query with real output), Deno (same flow plus the .ts
import-extension and permission-flag differences, both hit and
documented), and Hono (template scaffold, seed, GET /users served
over HTTP, plus an added POST route returning the created row).
Outputs in the guides are captured from the runs.
- Each guide documents the template's flat-model-path issue honestly
(db.orm.User -> db.orm.public.User) until the templates are fixed.
- Document the future guides URL cutover ("/" becomes /v7) as a
commented, reviewable block in next.config.mjs: promote
/guides/next/* to /guides/*, park converted Prisma 7 guides under
/guides/v7/*, per-guide pairs appended as each conversion lands.
- /guides/next index explains what is converted, what lands next per
DR-8689, and where to go meanwhile.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughThis PR adds a new "Prisma Next" guides section with pages for Bun, Deno, and Hono runtimes plus an index page, wired into meta.json files. It also extends version-routing and sidebar-tree logic across version.ts, versioned-sidebar-tree.ts, and version-switcher.tsx to support a new "Guides version" scope, plus a commented future redirect plan in next.config.mjs. ChangesPrisma Next Guides Documentation
Guides Version Routing
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related PRs
Alright, let's play detective — this PR is basically two well-separated changes stitched together, and both are clean: a batch of new guide pages (nicely repetitive, low logic density), and a genuinely new "Guides version" layer bolted onto existing routing plumbing with matching predicate/filter functions across three files. Nothing structurally surprising, just make sure the new Guides predicates don't accidentally shadow the existing ORM version logic when both are present. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
🍈 Lychee Link Check Report17 links: ✅ All links are working!Full Statistics Table
|
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
apps/docs/src/lib/version.ts (1)
236-261: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winFallback for unsupported guides target-version returns an ORM path.
If
targetVersionis anything other thanlatest/next, this returnsgetVersionRoot(targetVersion)(an/orm/...path) instead of a guides path. Today the UI only offerslatest/nextin the Guides dropdown, so this is unreachable — but the PR objectives themselves describe a near-term plan to park converted guides under/guides/v7/*. When that version is introduced, this branch will silently route a "Guides version" switch into the ORM docs instead of/guides/v7, which will be a confusing regression to debug later.♻️ Suggested fix
if (targetVersion !== LATEST_VERSION && targetVersion !== "next") { - return getVersionRoot(targetVersion); + return `${LATEST_GUIDES_ROOT}/${targetVersion}`; }Please confirm whether sibling functions like
getCliSwitchPathname/getGettingStartedSwitchPathnameuse the same ORM-root fallback convention intentionally — if so this may just need the same fix applied consistently there too.🤖 Prompt for 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. In `@apps/docs/src/lib/version.ts` around lines 236 - 261, The fallback in getGuidesSwitchPathname routes unsupported non-latest/non-next versions through getVersionRoot(targetVersion), which sends Guides switches to an ORM path instead of a guides path. Update this branch to return the appropriate guides root for converted versions (for example the planned /guides/v7-style root) and keep the fallback consistent with the other switch helpers like getCliSwitchPathname and getGettingStartedSwitchPathname if they share the same convention.
🤖 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/guides/next/hono.mdx`:
- Around line 74-80: The sample data in the Hono guide uses inconsistent `id`
types between the `GET /users` and `POST /users` examples. Update the example in
the `hono.mdx` content so the `id` shape matches the rest of the docs, using the
same representation in the response samples and related `users`/`createUser`
snippets to avoid implying different schemas.
- Around line 18-25: The setup section is inconsistent with the runtime note
because it mentions Node.js/npm support but only shows the Bun-based scaffold
command. Update the Hono guide example to match the stated runtimes by either
adding the equivalent npx-based scaffold command alongside the existing bunx
create-prisma@next example, or by narrowing the prerequisite text to Bun only;
keep the change centered around the scaffold instructions in the Hono guide.
---
Nitpick comments:
In `@apps/docs/src/lib/version.ts`:
- Around line 236-261: The fallback in getGuidesSwitchPathname routes
unsupported non-latest/non-next versions through getVersionRoot(targetVersion),
which sends Guides switches to an ORM path instead of a guides path. Update this
branch to return the appropriate guides root for converted versions (for example
the planned /guides/v7-style root) and keep the fallback consistent with the
other switch helpers like getCliSwitchPathname and
getGettingStartedSwitchPathname if they share the same convention.
🪄 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: b39d6edd-d91e-4ac3-940a-982b370c4a20
📒 Files selected for processing (10)
apps/docs/content/docs/guides/meta.jsonapps/docs/content/docs/guides/next/bun.mdxapps/docs/content/docs/guides/next/deno.mdxapps/docs/content/docs/guides/next/hono.mdxapps/docs/content/docs/guides/next/index.mdxapps/docs/content/docs/guides/next/meta.jsonapps/docs/next.config.mjsapps/docs/src/components/version-switcher.tsxapps/docs/src/lib/version.tsapps/docs/src/lib/versioned-sidebar-tree.ts
| - Node.js 24 or later, or [Bun](https://bun.sh/) (this guide uses Bun for speed; npm works the same) | ||
| - A PostgreSQL connection string, or nothing at all: the scaffold can create a [Prisma Postgres](/postgres) database for you | ||
|
|
||
| ## 1. Scaffold the project | ||
|
|
||
| ```bash | ||
| bunx create-prisma@next create my-hono-api --provider postgres --template hono | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '1,120p' apps/docs/content/docs/guides/next/hono.mdxRepository: prisma/web
Length of output: 4123
🏁 Script executed:
rg -n "create-prisma@next create|bunx create-prisma|npx create-prisma|pnpm dlx create-prisma|npm create-prisma" apps docs . --glob '!**/node_modules/**'Repository: prisma/web
Length of output: 4297
🏁 Script executed:
sed -n '1,120p' apps/docs/content/docs/guides/next/bun.mdx && printf '\n---\n' && sed -n '1,120p' apps/docs/content/docs/guides/next/deno.mdx && printf '\n---\n' && sed -n '1,80p' apps/docs/content/docs/(index)/next/getting-started.mdxRepository: prisma/web
Length of output: 453
🏁 Script executed:
sed -n '1,120p' 'apps/docs/content/docs/guides/next/bun.mdx' && printf '\n---\n' && sed -n '1,120p' 'apps/docs/content/docs/guides/next/deno.mdx' && printf '\n---\n' && sed -n '1,80p' 'apps/docs/content/docs/(index)/next/getting-started.mdx'Repository: prisma/web
Length of output: 10156
🏁 Script executed:
rg -n --fixed-strings -- "template hono" apps/docs/content docs apps/site | sed -n '1,120p'Repository: prisma/web
Length of output: 665
Make the setup path consistent with the runtime note. The prerequisite says Node.js/npm works too, but the scaffold example is Bun-specific (bunx ...). Either show the npx form here as well or narrow the guide to Bun.
🤖 Prompt for 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.
In `@apps/docs/content/docs/guides/next/hono.mdx` around lines 18 - 25, The setup
section is inconsistent with the runtime note because it mentions Node.js/npm
support but only shows the Bun-based scaffold command. Update the Hono guide
example to match the stated runtimes by either adding the equivalent npx-based
scaffold command alongside the existing bunx create-prisma@next example, or by
narrowing the prerequisite text to Bun only; keep the change centered around the
scaffold instructions in the Hono guide.
| ```json no-copy | ||
| [ | ||
| { "id": "1", "email": "alice@prisma.io", "username": "alice", "name": "Alice", "createdAt": "2026-07-06T23:37:32.440Z" }, | ||
| { "id": "2", "email": "bob@prisma.io", "username": "bob", "name": "Bob", "createdAt": "2026-07-06T23:37:32.474Z" }, | ||
| { "id": "3", "email": "carol@prisma.io", "username": "carol", "name": "Carol", "createdAt": "2026-07-06T23:37:32.507Z" } | ||
| ] | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Normalize the sample id type.
The captured JSON flips between quoted ids in GET /users and a numeric id in POST /users. Please make the examples match the same schema shape so readers don't infer two different models.
Also applies to: 108-110
🤖 Prompt for 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.
In `@apps/docs/content/docs/guides/next/hono.mdx` around lines 74 - 80, The sample
data in the Hono guide uses inconsistent `id` types between the `GET /users` and
`POST /users` examples. Update the example in the `hono.mdx` content so the `id`
shape matches the rest of the docs, using the same representation in the
response samples and related `users`/`createUser` snippets to avoid implying
different schemas.
1 participant
Adds the Prisma Next guides section behind a new Guides version dropdown, with the first tested batch of converted guides and the documented plan for the future URL cutover.
Linear: DR-8689
Version dropdown
The guides section now versions the same way the CLI section does:
/guidesstays the Prisma 7 tree,/guides/nextholds the Prisma Next tree, and the sidebar shows a "Guides version" dropdown on both. Implemented inversion.ts(pathname detection, switch-path mapping with available-path fallback, versioned nav), theVersionSwitcher, andversioned-sidebar-tree.ts(each version's sidebar hides the other tree). Verified in the rendered HTML: the latest view has zero anchors into/guides/next, and the next view scopes to its own tree.Converted guides (batch 1, every flow run end to end)
Each guide was executed against a live Prisma Postgres database (
bunx create-db) before writing; the outputs shown in the pages are captured from those runs./guides/next/bun)create-prismascaffold with Bun,contract:emit,db:init("Applied 5 operation(s)... database signed"), first typed query viabun run devwith its output/guides/next/deno)deno run -A npm:prisma-next ...; both Deno-specific gotchas were hit for real and documented: relative imports need the.tsextension, and the tsconfig options warning is harmless/guides/next/hono)--template honoscaffold, seed,GET /usersserved over HTTP with the JSON captured, plus an addedPOST /usersroute returning the created row (201)The guides are honest about one template issue: the generated
seed.ts/users.tsstill use the flatdb.orm.Userform, which crashes on 0.14.0, so each guide includes the one-line fix (db.orm.public.User) with a note that the step disappears when the templates are fixed (tracked alongside prisma-next#917).Conversion scope and queue
This is deliberately an incremental first batch per DR-8689 ("guides land one at a time, each tested before it ships"). The
/guides/nextindex page lists the queue: migration from Prisma 7, deployment targets, the remaining frameworks (Next.js, NestJS, SvelteKit, Astro, Nuxt, TanStack Start, Elysia), testing, patterns, performance, and operations. Converting the remaining Prisma 7 guides without running them would break the tested-examples bar this docs effort has held so far; each next batch follows this PR's pattern.Future redirects ("/" becomes "/v7")
Documented as a commented, reviewable block in
next.config.mjs("Guides URL cutover"): at the cutover,/guides/next/*is promoted to/guides/*and each converted Prisma 7 guide is parked under/guides/v7/*(unconverted guides keep their URLs). The per-guide pairs for bun, deno, and hono are already in the block; each future conversion appends its pair in the same PR. Nothing redirects today.Notes for reviewers
main(/orm/next, quickstarts). Once docs(next): Prisma Next Fundamentals section (DR-8681) #8011 (Fundamentals) and docs(orm/next): data modeling guides #8021 (Data modeling) merge, the "Next steps" links in these guides should be upgraded to point at those sections; happy to do that in a follow-up.types:checkclean,lint:links0 errors, cspell 0 issues, dev-server smoke test 200 on all five URLs with dropdown and sidebar behavior verified.🤖 Generated with Claude Code
Summary by CodeRabbit