docs(guides): Prisma Next guides with a Guides version dropdown (DR-8689)#8022
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.
|
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThis PR adds a new Prisma Next guides section with landing, framework, and runtime pages plus metadata, and extends docs version routing, sidebar filtering, and the version switcher to recognize a Guides version scope. A commented future redirect plan is also added. ChangesPrisma Next Guides Documentation
Guides Version Routing
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
🍈 Lychee Link Check Report64 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
… guide
Per review, /guides/next now mirrors the v7 guides layout (runtimes/,
frameworks/, with the DR-8689 groups joining as they land) instead of a
flat list, so the future promotion to /guides is a single wildcard:
/guides/next/:path* -> /guides/:path*. The commented cutover block in
next.config.mjs reflects that, plus the /guides/v7 parking pairs for
the four converted guides.
Adds the Elysia framework guide, run end to end against a live Prisma
Postgres database like the others (scaffold with --template elysia,
db init, seed, GET /users over HTTP with the captured response). URLs
move to /guides/next/runtimes/{bun,deno} and
/guides/next/frameworks/{hono,elysia}; the index cards and cross-links
follow.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Pushed 47e18d9 per review: /guides/next now mirrors the Prisma 7 guides folder structure (runtimes/, frameworks/, with the DR-8689 groups joining as each lands) instead of a flat list. That makes the future cutover promotion a single wildcard, /guides/next/:path* to /guides/:path*, and the commented block in next.config.mjs now says exactly that, plus /guides/v7 parking pairs per converted guide. Also adds a fourth tested conversion: Elysia (scaffolded with --template elysia, db init, seed, GET /users served over HTTP against a live Prisma Postgres database; response captured in the guide). Conversions stay limited to guides that can be run end to end, per the tested-examples bar. |
With the upstream template fix (namespace-qualified model access in generated seed.ts/users.ts) treated as merged, the guides drop the "update the starter query helpers" step and the bun gotcha. The post-fix flow is the one already verified end to end: scaffold, db:init, db:seed, serve (the earlier runs applied exactly the change the upstream fix makes). A short note under the seed step covers readers on an older scaffold: the exact error they would see and the one-line fix. Steps renumbered; the Elysia cross-link anchor follows. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Pushed c2be4fd: with the upstream template fix treated as merged, the guides drop the manual helper-fix step and the bun gotcha. The post-fix flow is the one already verified end to end (the earlier live runs applied exactly the change the fix makes: scaffold, db:init, db:seed, serve). A short note under the seed step still covers readers on an older scaffold, with the exact error and the one-line fix, so nobody gets stranded either way. Steps renumbered, anchors updated, and full validation re-run: types clean, links 0 errors, cspell 0 issues, all pages 200. |
…yle tree Every framework create-prisma ships a template for is now scaffolded, initialized, seeded, and served against a live Prisma Postgres database, and has a guide: Next.js (SSR page renders seeded users), NestJS (GET /users returns rows), SvelteKit (server load on :5173), Astro (page render + /api/users), Nuxt (page via /api/users), TanStack Start (server-fn query path verified, loader-rendered), plus the existing Hono and Elysia. solid-start and react-router-7 have no template yet, so no guide (tested-only bar). Tree now reads like /latest: bare framework names as titles (long form kept in metaTitle), no early-access badges, frameworks ordered like the Prisma 7 guides, and a Quick start one-liner per guide. The index is titled Overview and lists the full DR-8689 category set (migration, deployment, extensions, databases, patterns, performance, testing, operations) as coming, with cards for what exists. Cutover parking pairs in next.config.mjs extended to all ten converted guides. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/frameworks/nestjs.mdx`:
- Around line 46-49: The NestJS guide snippet is inconsistent because the seed
message says 3 users were seeded while the captured GET /users output shows only
one user. Update the example in the relevant docs section so the seed result and
the displayed response match, using the existing response block and seed text as
the anchors; either include all seeded users in the response shown or explicitly
indicate the response is truncated so readers are not misled.
- Around line 39-51: Move the older-scaffold workaround for db.orm.User to
db.orm.public.User into the db:seed step in the NestJS guide so readers see the
fix where the error occurs. Update the surrounding text in the Initialize and
seed the database section to include this note alongside the seed command
output, and keep the existing “Where things live” reference as a secondary
pointer if needed.
🪄 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: 4341d954-e45d-4672-a58a-f5592c8013ac
📒 Files selected for processing (13)
apps/docs/content/docs/guides/next/frameworks/astro.mdxapps/docs/content/docs/guides/next/frameworks/elysia.mdxapps/docs/content/docs/guides/next/frameworks/hono.mdxapps/docs/content/docs/guides/next/frameworks/meta.jsonapps/docs/content/docs/guides/next/frameworks/nestjs.mdxapps/docs/content/docs/guides/next/frameworks/nextjs.mdxapps/docs/content/docs/guides/next/frameworks/nuxt.mdxapps/docs/content/docs/guides/next/frameworks/sveltekit.mdxapps/docs/content/docs/guides/next/frameworks/tanstack-start.mdxapps/docs/content/docs/guides/next/index.mdxapps/docs/content/docs/guides/next/runtimes/bun.mdxapps/docs/content/docs/guides/next/runtimes/deno.mdxapps/docs/next.config.mjs
✅ Files skipped from review due to trivial changes (10)
- apps/docs/content/docs/guides/next/frameworks/nuxt.mdx
- apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx
- apps/docs/next.config.mjs
- apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx
- apps/docs/content/docs/guides/next/index.mdx
- apps/docs/content/docs/guides/next/frameworks/astro.mdx
- apps/docs/content/docs/guides/next/frameworks/hono.mdx
- apps/docs/content/docs/guides/next/runtimes/deno.mdx
- apps/docs/content/docs/guides/next/frameworks/nextjs.mdx
- apps/docs/content/docs/guides/next/frameworks/elysia.mdx
🚧 Files skipped from review as they are similar to previous changes (1)
- apps/docs/content/docs/guides/next/runtimes/bun.mdx
…ration categories - Every guide's Next steps now links the Fundamentals section (merged in #8011), and agent prompts link the transactions page where they reference one. - The upcoming-categories list disambiguates migration per review: "Upgrading" covers moving from Prisma 7 and between releases; "Migrations" covers the literal schema-migration guides (down migrations, schema conflicts, the migration graph). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Three updates since the last summary:
Validation: types clean, links 0 errors, cspell 0 issues, all eleven pages 200. Merge-ready. |
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # apps/docs/next.config.mjs
2 participants
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