From 7c8ab87fa2c5de45b9394ef7cd640f720c8c3fef Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 7 Jul 2026 01:48:20 +0200 Subject: [PATCH 1/5] docs(guides): add Prisma Next guides with a Guides version dropdown (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 --- apps/docs/content/docs/guides/meta.json | 1 + apps/docs/content/docs/guides/next/bun.mdx | 104 ++++++++++++++ apps/docs/content/docs/guides/next/deno.mdx | 98 +++++++++++++ apps/docs/content/docs/guides/next/hono.mdx | 132 ++++++++++++++++++ apps/docs/content/docs/guides/next/index.mdx | 43 ++++++ apps/docs/content/docs/guides/next/meta.json | 11 ++ apps/docs/next.config.mjs | 23 +++ apps/docs/src/components/version-switcher.tsx | 10 +- apps/docs/src/lib/version.ts | 71 +++++++++- apps/docs/src/lib/versioned-sidebar-tree.ts | 93 ++++++++++++ 10 files changed, 583 insertions(+), 3 deletions(-) create mode 100644 apps/docs/content/docs/guides/next/bun.mdx create mode 100644 apps/docs/content/docs/guides/next/deno.mdx create mode 100644 apps/docs/content/docs/guides/next/hono.mdx create mode 100644 apps/docs/content/docs/guides/next/index.mdx create mode 100644 apps/docs/content/docs/guides/next/meta.json diff --git a/apps/docs/content/docs/guides/meta.json b/apps/docs/content/docs/guides/meta.json index 64190da715..c3be0c49be 100644 --- a/apps/docs/content/docs/guides/meta.json +++ b/apps/docs/content/docs/guides/meta.json @@ -4,6 +4,7 @@ "icon": "NotebookTabs", "pages": [ "index", + "next", "frameworks", "runtimes", "deployment", diff --git a/apps/docs/content/docs/guides/next/bun.mdx b/apps/docs/content/docs/guides/next/bun.mdx new file mode 100644 index 0000000000..d49727735e --- /dev/null +++ b/apps/docs/content/docs/guides/next/bun.mdx @@ -0,0 +1,104 @@ +--- +title: How to use Prisma Next with Bun +description: Scaffold a Prisma Next app with Bun, initialize your database, and run your first typed query. +url: /guides/next/bun +metaTitle: How to use Prisma Next with Bun +metaDescription: Set up a Prisma Next project with Bun and Prisma Postgres, from scaffold to first query, with tested commands and real output. +badge: early-access +--- + +## Introduction + +In this guide, you scaffold a Prisma Next project with Bun, initialize a PostgreSQL database from your schema, and run your first typed query. Bun runs TypeScript directly, so there is no build step anywhere in the flow. + +Every command and code sample below was run end to end against a live Prisma Postgres database. + +## Prerequisites + +- [Bun](https://bun.sh/) 1.1 or later (`bun --version`) +- A PostgreSQL connection string, or nothing at all: the scaffold can create a [Prisma Postgres](/postgres) database for you + +## 1. Scaffold the project + +Create the project with `create-prisma`. Pick Bun as the package manager when prompted, or pass everything up front: + +```bash +bunx create-prisma@next create my-bun-app --provider postgres --package-manager bun +``` + +When the prompt asks about the database, pick Prisma Postgres to have one created for you, or paste your own `DATABASE_URL`. The scaffold writes the connection string to `.env`, sets up `src/prisma/` with a starter schema, and installs dependencies with Bun. + +```bash +cd my-bun-app +``` + +## 2. Emit the contract and initialize the database + +Prisma Next compiles your schema (`src/prisma/contract.prisma`) into a contract that your queries are type-checked against. Emit it, then apply the schema to the database: + +```bash +bun run contract:emit +bun run db:init +``` + +`db:init` creates the tables and signs the database: + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +``` + +If `db:init` reports that the contract file is missing, run `bun run contract:emit` first; the emit step generates `src/prisma/contract.json`. + +## 3. Write your first query + +Replace `src/index.ts` with a script that creates a user and reads every user back. Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`, where `public` is the default schema. + +```ts title="src/index.ts" +import { db } from "./prisma/db"; + +// Create a user, then read every user back +const user = await db.orm.public.User.create({ + email: `ada+${Date.now()}@prisma.io`, + name: "Ada Lovelace", +}); +console.log(`created user ${user.email}`); + +const users = await db.orm.public.User.select("id", "email", "name").all(); +console.log(`there are now ${users.length} users`); + +await db.close(); +``` + +`await db.close()` at the end lets the script exit cleanly; without it, the connection pool keeps the process alive. + +## 4. Run it + +```bash +bun run dev +``` + +```text no-copy +created user ada+1783380852695@prisma.io +there are now 2 users +``` + +That is the whole loop: schema to contract, contract to database, typed queries against both. + +## Common gotchas + +:::warning + +The starter `seed.ts` and `users.ts` files in some templates still address models with the older flat form (`db.orm.User`), which fails at runtime with `Cannot read properties of undefined`. If you use them, change the model access to `db.orm.public.User`. + +::: + +## Prompt your coding agent + +The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: + +- "Using the prisma-next-queries skill, add a script that lists the 10 newest users." +- "Add a Post model related to User, emit the contract, and update the database." + +## Next steps + +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/deno.mdx b/apps/docs/content/docs/guides/next/deno.mdx new file mode 100644 index 0000000000..75ac1daae3 --- /dev/null +++ b/apps/docs/content/docs/guides/next/deno.mdx @@ -0,0 +1,98 @@ +--- +title: How to use Prisma Next with Deno +description: Run Prisma Next on Deno, including the import-extension and permission differences that matter. +url: /guides/next/deno +metaTitle: How to use Prisma Next with Deno +metaDescription: Set up a Prisma Next project on Deno with Prisma Postgres, from scaffold to first query, with tested commands and real output. +badge: early-access +--- + +## Introduction + +In this guide, you scaffold a Prisma Next project for Deno, initialize a PostgreSQL database, and run your first typed query. Deno runs TypeScript natively and installs npm packages on demand, so the flow is close to the [Bun guide](/guides/next/bun) with two Deno-specific differences this guide calls out: explicit import extensions and permission flags. + +Every command and code sample below was run end to end against a live Prisma Postgres database. + +## Prerequisites + +- [Deno](https://deno.com/) 2.0 or later (`deno --version`) +- A PostgreSQL connection string, or nothing at all: the scaffold can create a [Prisma Postgres](/postgres) database for you + +## 1. Scaffold the project + +`create-prisma` supports Deno as a package manager choice: + +```bash +deno run -A npm:create-prisma@next create my-deno-app --provider postgres --package-manager deno +``` + +Pick Prisma Postgres at the database prompt to have a database created for you, or paste your own `DATABASE_URL`. The generated `package.json` scripts wrap every command in `deno run -A --env-file=.env`, so environment variables load without a dotenv import. + +```bash +cd my-deno-app +deno install +``` + +## 2. Emit the contract and initialize the database + +```bash +deno run -A --env-file=.env npm:prisma-next contract emit +deno run -A --env-file=.env npm:prisma-next db init +``` + +The first command compiles `src/prisma/contract.prisma` into the contract your queries are type-checked against. The second creates the tables and signs the database. + +The `-A` flag grants the permissions the CLI needs (network for the database, filesystem for the generated files). To scope permissions tighter, start from `--allow-net --allow-read --allow-write --allow-env` and adjust to your setup. + +## 3. Write your first query + +Replace `src/index.ts`. Two things to notice: Deno requires the `.ts` extension on relative imports, and model access is namespace-qualified on PostgreSQL (`db.orm.public.User`): + +```ts title="src/index.ts" +import { db } from "./prisma/db.ts"; + +// Create a user, then read every user back +const user = await db.orm.public.User.create({ + email: `grace+${Date.now()}@prisma.io`, + name: "Grace Hopper", +}); +console.log(`created user ${user.email}`); + +const users = await db.orm.public.User.select("id", "email", "name").all(); +console.log(`there are now ${users.length} users`); + +await db.close(); +``` + +If you see `Module not found "file:///…/src/prisma/db"`, the import is missing its `.ts` extension. Deno does not resolve relative imports without an extension. + +## 4. Run it + +```bash +deno task dev +``` + +```text no-copy +created user grace+1783380988819@prisma.io +there are now 3 users +``` + +## Common gotchas + +:::warning + +Deno reports `Unsupported compiler options in tsconfig.json` for a few options the scaffold sets for Node compatibility. The warning is harmless: Deno ignores those options and runs the code the same way. + +::: + +## Prompt your coding agent + +The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: + +- "Using the prisma-next-queries skill, add a Deno task that prints every user created in the last day." +- "Tighten the Deno permissions for this project from -A to an explicit allow list." + +## Next steps + +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. +- [Use the Bun guide](/guides/next/bun) if you also target Bun; the flow is the same apart from the runtime differences above. diff --git a/apps/docs/content/docs/guides/next/hono.mdx b/apps/docs/content/docs/guides/next/hono.mdx new file mode 100644 index 0000000000..6eb1cadbeb --- /dev/null +++ b/apps/docs/content/docs/guides/next/hono.mdx @@ -0,0 +1,132 @@ +--- +title: How to use Prisma Next with Hono +description: Build a Hono API on Prisma Next with the hono template, then add your own routes. +url: /guides/next/hono +metaTitle: How to use Prisma Next with Hono +metaDescription: Scaffold a Hono API backed by Prisma Next and Prisma Postgres, seed it, serve users over HTTP, and add a POST route, with tested commands and output. +badge: early-access +--- + +## Introduction + +In this guide, you scaffold a Hono API backed by Prisma Next, initialize and seed a PostgreSQL database, serve data over HTTP, and add your own POST route. The `hono` template generates the server for you, so most of the work is understanding the pieces and extending them. + +Every command, route, and response below was run end to end against a live Prisma Postgres database. + +## Prerequisites + +- 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 +``` + +Pick your package manager and database at the prompts. The template generates a Hono server in `src/index.ts` with two routes (`GET /` and `GET /users`), the Prisma Next setup in `src/prisma/`, and package scripts for the database steps. + +```bash +cd my-hono-api +``` + +## 2. Update the starter query helpers + +Model access is namespace-qualified on PostgreSQL (`db.orm.public.User`), and the current template's helper files still use the older flat form, which fails at runtime. Open `src/prisma/users.ts` and `src/prisma/seed.ts` and change every `db.orm.User` to `db.orm.public.User`: + +```ts title="src/prisma/users.ts" +const users = await db.orm.public.User + .select("id", "email", "username", "name", "createdAt") + .take(limit) + .all(); +``` + +:::note + +This is a known template issue and will disappear from this guide once the template is updated. + +::: + +## 3. Initialize and seed the database + +```bash +bun run db:init +bun run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +## 4. Run the server + +```bash +bun run dev +``` + +The server starts on port 3000 (set `PORT` to change it). Check both routes: + +```bash +curl http://localhost:3000/users +``` + +```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" } +] +``` + +The route handler is ordinary Hono code calling an ordinary Prisma Next query; there is no framework adapter in between. + +## 5. Add a POST route + +Add a route that creates a user from the request body. Add this to `src/index.ts` above the `serve(...)` call: + +```ts title="src/index.ts" +app.post("/users", async (c) => { + const body = await c.req.json<{ email: string; name?: string }>(); + const { db } = await import("./prisma/db"); + const user = await db.orm.public.User.create({ + email: body.email, + name: body.name ?? null, + }); + return c.json(user, 201); +}); +``` + +Restart the server and create a user: + +```bash +curl -X POST http://localhost:3000/users \ + -H "content-type: application/json" \ + -d '{"email":"dev@prisma.io","name":"Dev"}' +``` + +```json no-copy +{ "createdAt": "2026-07-06T23:37:56.184Z", "email": "dev@prisma.io", "id": 4, "name": "Dev", "username": null } +``` + +`.create(...)` returns the full inserted record, database defaults included, so the response needs no second query. + +## Common gotchas + +:::warning + +In a long-running server, don't call `db.close()` in route handlers; the client's connection pool is shared across requests. Close it only on process shutdown. + +::: + +## Prompt your coding agent + +The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: + +- "Using the prisma-next-queries skill, add GET /users/:id that returns one user or a 404." +- "Add a Post model related to User, update the database, and expose GET /users/:id/posts." +- "Wrap the signup route's writes in a transaction." + +## Next steps + +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/index.mdx b/apps/docs/content/docs/guides/next/index.mdx new file mode 100644 index 0000000000..19a1505b93 --- /dev/null +++ b/apps/docs/content/docs/guides/next/index.mdx @@ -0,0 +1,43 @@ +--- +title: Prisma Next guides +description: Start-to-finish guides for building with Prisma Next, converted from the Prisma 7 guides as each one is tested. +url: /guides/next +metaTitle: Prisma Next guides +metaDescription: Hands-on Prisma Next guides for runtimes and frameworks, with tested examples. More groups land incrementally, including deployment, testing, and migration. +badge: early-access +--- + +These guides take you from an empty directory to a working result with Prisma Next. Every command and code sample in a published guide was run end to end against a live database before it landed here. + +Use the version dropdown in the sidebar to switch between these guides and the Prisma 7 guides. The Prisma 7 versions stay where they are until Prisma Next becomes the default. + +## Available now + + + }> + Scaffold a Prisma Next app with Bun, initialize Prisma Postgres, and run your first typed query. + + }> + Run Prisma Next on Deno, including the import and permission differences that matter. + + }> + Build a Hono API on Prisma Next with the hono template, and add your own routes. + + + +## Coming as they land + +The guide groups follow the [Prisma Next docs plan](https://linear.app/prisma-company/issue/DR-8689/docs-guides-incremental-migration-deployment-performance-testing) and land one at a time, each tested before it ships: + +- Migration: moving from Prisma 7, and between Prisma Next releases +- Deployment: Vercel, Fly.io, AWS Lambda, Cloudflare Workers, Docker +- Frameworks: Next.js, NestJS, SvelteKit, Astro, Nuxt, TanStack Start, Elysia +- Testing: unit tests, integration tests, testing against the contract +- Patterns, performance, and operations + +Until a Prisma Next guide exists for your topic, the [Prisma 7 guide](/guides) still applies to Prisma 7 projects, and the [Prisma Next overview](/orm/next) covers the concepts any guide builds on. + +## Next steps + +- [Start with the quickstart](/next/quickstart/postgresql) if you don't have a Prisma Next project yet. +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts, typed queries, and migrations. diff --git a/apps/docs/content/docs/guides/next/meta.json b/apps/docs/content/docs/guides/next/meta.json new file mode 100644 index 0000000000..e45f7e2594 --- /dev/null +++ b/apps/docs/content/docs/guides/next/meta.json @@ -0,0 +1,11 @@ +{ + "title": "Next", + "pages": [ + "index", + "---Runtimes---", + "bun", + "deno", + "---Frameworks---", + "hono" + ] +} diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index dfc0f742f5..32d828a9b4 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -297,6 +297,29 @@ const config = { destination: "/next/add-to-existing-project/:path*", permanent: false, }, + // ── Guides URL cutover (DR-8689 / DR-8687) — DO NOT ENABLE YET ──────── + // Today: Prisma 7 guides live at /guides/* and Prisma Next guides at + // /guides/next/* (the "Guides version" dropdown switches between them). + // When Prisma Next becomes the default docs version ("/" becomes the + // Prisma Next docs and Prisma 7 moves to v7), the guides flip the same + // way: the Prisma 7 guide tree moves under /guides/v7, and the + // /guides/next tree is promoted to /guides. The redirects to enable at + // that cutover, kept here so the map builds up in one reviewable place: + // + // 1. Promote every converted Prisma Next guide (per-guide, as converted): + // { source: "/guides/next/bun", destination: "/guides/bun", permanent: false }, + // { source: "/guides/next/deno", destination: "/guides/deno", permanent: false }, + // { source: "/guides/next/hono", destination: "/guides/hono", permanent: false }, + // { source: "/guides/next", destination: "/guides", permanent: false }, + // + // 2. Park the Prisma 7 versions under /guides/v7 (only for guides that + // have a Prisma Next replacement; unconverted guides keep their URL): + // { source: "/guides/runtimes/bun", destination: "/guides/v7/runtimes/bun", permanent: false }, + // { source: "/guides/runtimes/deno", destination: "/guides/v7/runtimes/deno", permanent: false }, + // { source: "/guides/frameworks/hono", destination: "/guides/v7/frameworks/hono", permanent: false }, + // + // Each future guide conversion appends its pair here in the same PR. + // ─────────────────────────────────────────────────────────────────────── ]; }, async rewrites() { diff --git a/apps/docs/src/components/version-switcher.tsx b/apps/docs/src/components/version-switcher.tsx index 1c7b0369d6..42ec916fe4 100644 --- a/apps/docs/src/components/version-switcher.tsx +++ b/apps/docs/src/components/version-switcher.tsx @@ -6,11 +6,13 @@ import { ChevronDownIcon } from "lucide-react"; import { getCliVersionFromPathname, getGettingStartedVersionFromPathname, + getGuidesVersionFromPathname, getOrmVersionFromPathname, getVersionLabel, getVersionSwitchPathname, isCliVersionPathname, isGettingStartedVersionPathname, + isGuidesVersionPathname, LATEST_VERSION, type Version, } from "@/lib/version"; @@ -34,6 +36,7 @@ export function VersionSwitcher({ const router = useRouter(); const isGettingStartedVersion = isGettingStartedVersionPathname(pathname); const isCliVersion = isCliVersionPathname(pathname); + const isGuidesVersion = isGuidesVersionPathname(pathname); // Getting Started no longer has a version toggle: Prisma Next lives inline in the // getting-started sidebar as its own sections, so there is no "Docs version" dropdown. @@ -44,9 +47,10 @@ export function VersionSwitcher({ const detectedVersion = getGettingStartedVersionFromPathname(pathname) ?? getCliVersionFromPathname(pathname) ?? + getGuidesVersionFromPathname(pathname) ?? getOrmVersionFromPathname(pathname); const currentVersion = detectedVersion ?? null; - const usesScopedVersions = isGettingStartedVersion || isCliVersion; + const usesScopedVersions = isGettingStartedVersion || isCliVersion || isGuidesVersion; const visibleVersions = usesScopedVersions ? versions.filter((version) => version === LATEST_VERSION || version === "next") : versions; @@ -54,7 +58,9 @@ export function VersionSwitcher({ ? "Docs version" : isCliVersion ? "CLI version" - : "ORM version"; + : isGuidesVersion + ? "Guides version" + : "ORM version"; if (!currentVersion || !visibleVersions.includes(currentVersion)) { return null; diff --git a/apps/docs/src/lib/version.ts b/apps/docs/src/lib/version.ts index f19a63c1b8..484209e3a7 100644 --- a/apps/docs/src/lib/version.ts +++ b/apps/docs/src/lib/version.ts @@ -20,6 +20,8 @@ const DOCS_PREFIX = "/docs"; const NEXT_GETTING_STARTED_ROOT = "/next"; const LATEST_CLI_ROOT = "/cli"; const NEXT_CLI_ROOT = "/cli/next"; +const LATEST_GUIDES_ROOT = "/guides"; +const NEXT_GUIDES_ROOT = "/guides/next"; const NEXT_GETTING_STARTED_PATHS_BY_LATEST_PATH = new Map([ ["/", NEXT_GETTING_STARTED_ROOT], ["/getting-started", "/next/getting-started"], @@ -220,6 +222,62 @@ function isNextCliPathname(pathname: string) { return pathname === NEXT_CLI_ROOT || pathname.startsWith(`${NEXT_CLI_ROOT}/`); } +function isLatestGuidesPathname(pathname: string) { + return ( + pathname === LATEST_GUIDES_ROOT || + (pathname.startsWith(`${LATEST_GUIDES_ROOT}/`) && !isNextGuidesPathname(pathname)) + ); +} + +function isNextGuidesPathname(pathname: string) { + return pathname === NEXT_GUIDES_ROOT || pathname.startsWith(`${NEXT_GUIDES_ROOT}/`); +} + +function getGuidesSwitchPathname( + docsPathname: string, + targetVersion: Version, + availablePathnames: Iterable, +) { + if (targetVersion !== LATEST_VERSION && targetVersion !== "next") { + return getVersionRoot(targetVersion); + } + + const targetRoot = targetVersion === "next" ? NEXT_GUIDES_ROOT : LATEST_GUIDES_ROOT; + const currentRoot = isNextGuidesPathname(docsPathname) ? NEXT_GUIDES_ROOT : LATEST_GUIDES_ROOT; + const suffix = + docsPathname === currentRoot + ? "" + : docsPathname.startsWith(`${currentRoot}/`) + ? docsPathname.slice(currentRoot.length) + : ""; + const candidate = `${targetRoot}${suffix}`; + const available = getAvailablePathnameSet(availablePathnames); + + if (available.size === 0 || available.has(candidate)) { + return candidate; + } + + return targetRoot; +} + +export function getGuidesVersionFromPathname(pathname: string): Version | null { + const docsPathname = withoutDocsPrefix(pathname); + + if (isNextGuidesPathname(docsPathname)) { + return "next"; + } + + if (isLatestGuidesPathname(docsPathname)) { + return LATEST_VERSION; + } + + return null; +} + +export function isGuidesVersionPathname(pathname: string) { + return getGuidesVersionFromPathname(pathname) !== null; +} + function getAvailablePathnameSet(availablePathnames: Iterable) { return new Set( Array.from(availablePathnames, (availablePathname) => withoutDocsPrefix(availablePathname)), @@ -324,6 +382,12 @@ export function getVersionSwitchPathname( return getCliSwitchPathname(docsPathname, targetVersion, availablePathnames); } + const guidesVersion = getGuidesVersionFromPathname(docsPathname); + + if (guidesVersion) { + return getGuidesSwitchPathname(docsPathname, targetVersion, availablePathnames); + } + const currentVersion = getOrmVersionFromPathname(docsPathname); const targetRoot = getVersionRoot(targetVersion); @@ -353,7 +417,8 @@ export function getVersionedNavPathname(targetPathname: string, currentPathname: const isNextDocsPathname = getGettingStartedVersionFromPathname(currentPathname) === "next" || getOrmVersionFromPathname(currentPathname) === "next" || - getCliVersionFromPathname(currentPathname) === "next"; + getCliVersionFromPathname(currentPathname) === "next" || + getGuidesVersionFromPathname(currentPathname) === "next"; // Bare "/" redirects to /next, so route the Getting Started tab to the reachable // landing for the active version instead of the redirecting root. @@ -373,6 +438,10 @@ export function getVersionedNavPathname(targetPathname: string, currentPathname: return NEXT_CLI_ROOT; } + if (targetDocsPathname === LATEST_GUIDES_ROOT) { + return NEXT_GUIDES_ROOT; + } + return targetPathname; } diff --git a/apps/docs/src/lib/versioned-sidebar-tree.ts b/apps/docs/src/lib/versioned-sidebar-tree.ts index 23056cad90..a350490968 100644 --- a/apps/docs/src/lib/versioned-sidebar-tree.ts +++ b/apps/docs/src/lib/versioned-sidebar-tree.ts @@ -3,6 +3,7 @@ import { LATEST_VERSION, getCliVersionFromPathname, getGettingStartedVersionFromPathname, + getGuidesVersionFromPathname, getOrmVersionFromRoute, getOrmVersions, getVersionRoot, @@ -37,6 +38,10 @@ function isCliNode(node: TreeNode) { return node.type === "folder" && (node.name === "CLI" || node.index?.url === "/cli"); } +function isGuidesNode(node: TreeNode) { + return node.type === "folder" && (node.name === "Guides" || node.index?.url === "/guides"); +} + function isGettingStartedVersionNode(node: TreeNode, version: Version) { if (node.type !== "folder") { return false; @@ -70,6 +75,20 @@ function isCliVersionNode(node: TreeNode, version: Version) { return false; } +function isGuidesVersionNode(node: TreeNode, version: Version) { + if (node.type !== "folder") { + return false; + } + + const name = String(node.name ?? "").toLowerCase(); + + if (version === "next") { + return name === "next" || node.index?.url === "/guides/next"; + } + + return false; +} + function isVersionNode(node: TreeNode, version: Version) { if (node.type !== "folder") { return false; @@ -183,6 +202,40 @@ function filterCliSidebarTree(node: TreeNode, version: Version): TreeNode { }; } +function filterGuidesSidebarTree(node: TreeNode, version: Version): TreeNode { + const children = node.children?.map((child) => filterGuidesSidebarTree(child, version)); + + if (!children) { + return node; + } + + if (isGuidesNode(node)) { + const versionChildren = children.filter((child) => isGuidesVersionNode(child, "next")); + + if (version === "next") { + const selectedVersion = versionChildren.find((child) => isGuidesVersionNode(child, version)); + + if (selectedVersion?.children) { + return { + ...node, + index: selectedVersion.index ?? node.index, + children: selectedVersion.children, + }; + } + } + + return { + ...node, + children: children.filter((child) => !versionChildren.includes(child)), + }; + } + + return { + ...node, + children, + }; +} + function filterOrmSidebarTree(node: TreeNode, version: Version): TreeNode { const children = node.children?.map((child) => filterOrmSidebarTree(child, version)); @@ -257,6 +310,40 @@ function getGettingStartedSidebarTree(tree: TreeRootNode, version: Version): Tre }; } +function findGuidesNode(node: TreeNode): TreeNode | null { + if (isGuidesNode(node)) { + return node; + } + + for (const child of node.children ?? []) { + const guidesNode = findGuidesNode(child); + if (guidesNode) { + return guidesNode; + } + } + + return null; +} + +function getGuidesSidebarTree(tree: TreeRootNode, version: Version): TreeRootNode { + const filteredTree = filterGuidesSidebarTree(tree, version) as TreeRootNode; + + if (isGuidesNode(filteredTree)) { + return filteredTree; + } + + const guidesNode = findGuidesNode(filteredTree); + + if (!guidesNode) { + return filteredTree; + } + + return { + ...filteredTree, + children: [guidesNode], + }; +} + function getCliSidebarTree(tree: TreeRootNode, version: Version): TreeRootNode { const filteredTree = filterCliSidebarTree(tree, version) as TreeRootNode; @@ -293,6 +380,12 @@ export function getVersionedSidebarTree(tree: PageTree.Root, route?: string | st return getCliSidebarTree(tree as TreeRootNode, cliVersion) as PageTree.Root; } + const guidesVersion = typeof route === "string" ? getGuidesVersionFromPathname(route) : null; + + if (guidesVersion) { + return getGuidesSidebarTree(tree as TreeRootNode, guidesVersion) as PageTree.Root; + } + const versions = getOrmVersions(tree); const explicitVersions = versions.filter((version) => version !== LATEST_VERSION); const version = getOrmVersionFromRoute(route); From 47e18d924b7bc4d1043c2b614621e7a0fbcf2270 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 7 Jul 2026 10:56:46 +0200 Subject: [PATCH 2/5] docs(guides): mirror the Prisma 7 folder structure, add tested Elysia 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 --- .../docs/guides/next/frameworks/elysia.mdx | 102 ++++++++++++++++++ .../guides/next/{ => frameworks}/hono.mdx | 2 +- .../docs/guides/next/frameworks/meta.json | 5 + apps/docs/content/docs/guides/next/index.mdx | 8 +- apps/docs/content/docs/guides/next/meta.json | 7 +- .../docs/guides/next/{ => runtimes}/bun.mdx | 2 +- .../docs/guides/next/{ => runtimes}/deno.mdx | 6 +- .../docs/guides/next/runtimes/meta.json | 1 + apps/docs/next.config.mjs | 13 ++- 9 files changed, 125 insertions(+), 21 deletions(-) create mode 100644 apps/docs/content/docs/guides/next/frameworks/elysia.mdx rename apps/docs/content/docs/guides/next/{ => frameworks}/hono.mdx (99%) create mode 100644 apps/docs/content/docs/guides/next/frameworks/meta.json rename apps/docs/content/docs/guides/next/{ => runtimes}/bun.mdx (99%) rename apps/docs/content/docs/guides/next/{ => runtimes}/deno.mdx (91%) create mode 100644 apps/docs/content/docs/guides/next/runtimes/meta.json diff --git a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx new file mode 100644 index 0000000000..6d487c5902 --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx @@ -0,0 +1,102 @@ +--- +title: How to use Prisma Next with Elysia +description: Build an Elysia API on Prisma Next with the elysia template. +url: /guides/next/frameworks/elysia +metaTitle: How to use Prisma Next with Elysia +metaDescription: Scaffold an Elysia API backed by Prisma Next and Prisma Postgres, seed it, and serve users over HTTP, with tested commands and output. +badge: early-access +--- + +## Introduction + +In this guide, you scaffold an Elysia API backed by Prisma Next, initialize and seed a PostgreSQL database, and serve data over HTTP. The `elysia` template generates the server, so most of the work is understanding the pieces. + +Every command and response below was run end to end against a live Prisma Postgres database. + +## Prerequisites + +- [Bun](https://bun.sh/) 1.1 or later (Elysia is Bun-first) +- 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-elysia-api --provider postgres --template elysia +``` + +Pick your database at the prompt. The template generates an Elysia server in `src/index.ts` with `GET /` and `GET /users` routes, the Prisma Next setup in `src/prisma/`, and package scripts for the database steps. + +```bash +cd my-elysia-api +``` + +## 2. Update the starter query helpers + +Model access is namespace-qualified on PostgreSQL (`db.orm.public.User`), and the current template's helper files still use the older flat form, which fails at runtime. Open `src/prisma/users.ts` and `src/prisma/seed.ts` and change every `db.orm.User` to `db.orm.public.User`: + +```ts title="src/prisma/users.ts" +const users = await db.orm.public.User + .select("id", "email", "username", "name", "createdAt") + .take(limit) + .all(); +``` + +:::note + +This is a known template issue and will disappear from this guide once the template is updated. + +::: + +## 3. Initialize and seed the database + +```bash +bun run db:init +bun run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +## 4. Run the server + +```bash +bun run dev +``` + +The server starts on port 3000 (set `PORT` to change it): + +```bash +curl http://localhost:3000/users +``` + +```json no-copy +[ + { "id": "1", "email": "alice@prisma.io", "username": "alice", "name": "Alice", "createdAt": "2026-07-07T08:51:14.054Z" }, + { "id": "2", "email": "bob@prisma.io", "username": "bob", "name": "Bob", "createdAt": "2026-07-07T08:51:14.089Z" }, + { "id": "3", "email": "carol@prisma.io", "username": "carol", "name": "Carol", "createdAt": "2026-07-07T08:51:14.122Z" } +] +``` + +The route handler is ordinary Elysia code calling an ordinary Prisma Next query; there is no framework adapter in between. To add write routes, follow the same pattern as the [Hono guide's POST route](/guides/next/frameworks/hono#5-add-a-post-route); the query code is identical. + +## Common gotchas + +:::warning + +In a long-running server, don't call `db.close()` in route handlers; the client's connection pool is shared across requests. Close it only on process shutdown. + +::: + +## Prompt your coding agent + +The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: + +- "Using the prisma-next-queries skill, add GET /users/:id that returns one user or a 404." +- "Add a POST /users route that creates a user from the request body." + +## Next steps + +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. +- [Use the Hono guide](/guides/next/frameworks/hono) for the tested POST route pattern. diff --git a/apps/docs/content/docs/guides/next/hono.mdx b/apps/docs/content/docs/guides/next/frameworks/hono.mdx similarity index 99% rename from apps/docs/content/docs/guides/next/hono.mdx rename to apps/docs/content/docs/guides/next/frameworks/hono.mdx index 6eb1cadbeb..37ee74b220 100644 --- a/apps/docs/content/docs/guides/next/hono.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/hono.mdx @@ -1,7 +1,7 @@ --- title: How to use Prisma Next with Hono description: Build a Hono API on Prisma Next with the hono template, then add your own routes. -url: /guides/next/hono +url: /guides/next/frameworks/hono metaTitle: How to use Prisma Next with Hono metaDescription: Scaffold a Hono API backed by Prisma Next and Prisma Postgres, seed it, serve users over HTTP, and add a POST route, with tested commands and output. badge: early-access diff --git a/apps/docs/content/docs/guides/next/frameworks/meta.json b/apps/docs/content/docs/guides/next/frameworks/meta.json new file mode 100644 index 0000000000..e8080c5f9f --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Frameworks", + "defaultOpen": true, + "pages": ["hono", "elysia"] +} diff --git a/apps/docs/content/docs/guides/next/index.mdx b/apps/docs/content/docs/guides/next/index.mdx index 19a1505b93..9a13e729b5 100644 --- a/apps/docs/content/docs/guides/next/index.mdx +++ b/apps/docs/content/docs/guides/next/index.mdx @@ -7,20 +7,20 @@ metaDescription: Hands-on Prisma Next guides for runtimes and frameworks, with t badge: early-access --- -These guides take you from an empty directory to a working result with Prisma Next. Every command and code sample in a published guide was run end to end against a live database before it landed here. +These guides take you from an empty directory to a working result with Prisma Next. They mirror the structure of the [Prisma 7 guides](/guides): the same folders, converted one guide at a time, and only after every command in a guide was run end to end against a live database. Use the version dropdown in the sidebar to switch between these guides and the Prisma 7 guides. The Prisma 7 versions stay where they are until Prisma Next becomes the default. ## Available now - }> + }> Scaffold a Prisma Next app with Bun, initialize Prisma Postgres, and run your first typed query. - }> + }> Run Prisma Next on Deno, including the import and permission differences that matter. - }> + }> Build a Hono API on Prisma Next with the hono template, and add your own routes. diff --git a/apps/docs/content/docs/guides/next/meta.json b/apps/docs/content/docs/guides/next/meta.json index e45f7e2594..6f57759d5a 100644 --- a/apps/docs/content/docs/guides/next/meta.json +++ b/apps/docs/content/docs/guides/next/meta.json @@ -2,10 +2,7 @@ "title": "Next", "pages": [ "index", - "---Runtimes---", - "bun", - "deno", - "---Frameworks---", - "hono" + "frameworks", + "runtimes" ] } diff --git a/apps/docs/content/docs/guides/next/bun.mdx b/apps/docs/content/docs/guides/next/runtimes/bun.mdx similarity index 99% rename from apps/docs/content/docs/guides/next/bun.mdx rename to apps/docs/content/docs/guides/next/runtimes/bun.mdx index d49727735e..e4b25c30af 100644 --- a/apps/docs/content/docs/guides/next/bun.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/bun.mdx @@ -1,7 +1,7 @@ --- title: How to use Prisma Next with Bun description: Scaffold a Prisma Next app with Bun, initialize your database, and run your first typed query. -url: /guides/next/bun +url: /guides/next/runtimes/bun metaTitle: How to use Prisma Next with Bun metaDescription: Set up a Prisma Next project with Bun and Prisma Postgres, from scaffold to first query, with tested commands and real output. badge: early-access diff --git a/apps/docs/content/docs/guides/next/deno.mdx b/apps/docs/content/docs/guides/next/runtimes/deno.mdx similarity index 91% rename from apps/docs/content/docs/guides/next/deno.mdx rename to apps/docs/content/docs/guides/next/runtimes/deno.mdx index 75ac1daae3..864c7d04f3 100644 --- a/apps/docs/content/docs/guides/next/deno.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/deno.mdx @@ -1,7 +1,7 @@ --- title: How to use Prisma Next with Deno description: Run Prisma Next on Deno, including the import-extension and permission differences that matter. -url: /guides/next/deno +url: /guides/next/runtimes/deno metaTitle: How to use Prisma Next with Deno metaDescription: Set up a Prisma Next project on Deno with Prisma Postgres, from scaffold to first query, with tested commands and real output. badge: early-access @@ -9,7 +9,7 @@ badge: early-access ## Introduction -In this guide, you scaffold a Prisma Next project for Deno, initialize a PostgreSQL database, and run your first typed query. Deno runs TypeScript natively and installs npm packages on demand, so the flow is close to the [Bun guide](/guides/next/bun) with two Deno-specific differences this guide calls out: explicit import extensions and permission flags. +In this guide, you scaffold a Prisma Next project for Deno, initialize a PostgreSQL database, and run your first typed query. Deno runs TypeScript natively and installs npm packages on demand, so the flow is close to the [Bun guide](/guides/next/runtimes/bun) with two Deno-specific differences this guide calls out: explicit import extensions and permission flags. Every command and code sample below was run end to end against a live Prisma Postgres database. @@ -95,4 +95,4 @@ The scaffold installs Prisma Next skills for your coding agent. Prompts that map ## Next steps - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. -- [Use the Bun guide](/guides/next/bun) if you also target Bun; the flow is the same apart from the runtime differences above. +- [Use the Bun guide](/guides/next/runtimes/bun) if you also target Bun; the flow is the same apart from the runtime differences above. diff --git a/apps/docs/content/docs/guides/next/runtimes/meta.json b/apps/docs/content/docs/guides/next/runtimes/meta.json new file mode 100644 index 0000000000..e44177cc17 --- /dev/null +++ b/apps/docs/content/docs/guides/next/runtimes/meta.json @@ -0,0 +1 @@ +{ "title": "Runtimes", "pages": ["bun", "deno"] } diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index 32d828a9b4..01ff33317e 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -306,17 +306,16 @@ const config = { // /guides/next tree is promoted to /guides. The redirects to enable at // that cutover, kept here so the map builds up in one reviewable place: // - // 1. Promote every converted Prisma Next guide (per-guide, as converted): - // { source: "/guides/next/bun", destination: "/guides/bun", permanent: false }, - // { source: "/guides/next/deno", destination: "/guides/deno", permanent: false }, - // { source: "/guides/next/hono", destination: "/guides/hono", permanent: false }, - // { source: "/guides/next", destination: "/guides", permanent: false }, + // The /guides/next tree mirrors the Prisma 7 folder structure, so the + // promotion is one wildcard: + // { source: "/guides/next/:path*", destination: "/guides/:path*", permanent: false }, // - // 2. Park the Prisma 7 versions under /guides/v7 (only for guides that - // have a Prisma Next replacement; unconverted guides keep their URL): + // Park the Prisma 7 versions under /guides/v7 (only for guides that + // have a Prisma Next replacement; unconverted guides keep their URL): // { source: "/guides/runtimes/bun", destination: "/guides/v7/runtimes/bun", permanent: false }, // { source: "/guides/runtimes/deno", destination: "/guides/v7/runtimes/deno", permanent: false }, // { source: "/guides/frameworks/hono", destination: "/guides/v7/frameworks/hono", permanent: false }, + // { source: "/guides/frameworks/elysia", destination: "/guides/v7/frameworks/elysia", permanent: false }, // // Each future guide conversion appends its pair here in the same PR. // ─────────────────────────────────────────────────────────────────────── From c2be4fd307afd9244ecc91e7a27a76a90009c237 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 7 Jul 2026 11:08:02 +0200 Subject: [PATCH 3/5] docs(guides): assume fixed scaffold templates; keep a fallback note 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 --- .../docs/guides/next/frameworks/elysia.mdx | 29 ++++++------------- .../docs/guides/next/frameworks/hono.mdx | 29 ++++++------------- .../content/docs/guides/next/runtimes/bun.mdx | 8 ----- 3 files changed, 18 insertions(+), 48 deletions(-) diff --git a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx index 6d487c5902..2dbc933342 100644 --- a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx @@ -30,24 +30,7 @@ Pick your database at the prompt. The template generates an Elysia server in `sr cd my-elysia-api ``` -## 2. Update the starter query helpers - -Model access is namespace-qualified on PostgreSQL (`db.orm.public.User`), and the current template's helper files still use the older flat form, which fails at runtime. Open `src/prisma/users.ts` and `src/prisma/seed.ts` and change every `db.orm.User` to `db.orm.public.User`: - -```ts title="src/prisma/users.ts" -const users = await db.orm.public.User - .select("id", "email", "username", "name", "createdAt") - .take(limit) - .all(); -``` - -:::note - -This is a known template issue and will disappear from this guide once the template is updated. - -::: - -## 3. Initialize and seed the database +## 2. Initialize and seed the database ```bash bun run db:init @@ -59,7 +42,13 @@ bun run db:seed Seeded 3 users. ``` -## 4. Run the server +:::note + +Scaffolded with an older `create-prisma` and seeing `Cannot read properties of undefined (reading 'where')`? Update `db.orm.User` to `db.orm.public.User` in `src/prisma/seed.ts` and `src/prisma/users.ts`. Current templates generate the qualified form. + +::: + +## 3. Run the server ```bash bun run dev @@ -79,7 +68,7 @@ curl http://localhost:3000/users ] ``` -The route handler is ordinary Elysia code calling an ordinary Prisma Next query; there is no framework adapter in between. To add write routes, follow the same pattern as the [Hono guide's POST route](/guides/next/frameworks/hono#5-add-a-post-route); the query code is identical. +The route handler is ordinary Elysia code calling an ordinary Prisma Next query; there is no framework adapter in between. To add write routes, follow the same pattern as the [Hono guide's POST route](/guides/next/frameworks/hono#4-add-a-post-route); the query code is identical. ## Common gotchas diff --git a/apps/docs/content/docs/guides/next/frameworks/hono.mdx b/apps/docs/content/docs/guides/next/frameworks/hono.mdx index 37ee74b220..19fc7a8dbe 100644 --- a/apps/docs/content/docs/guides/next/frameworks/hono.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/hono.mdx @@ -30,24 +30,7 @@ Pick your package manager and database at the prompts. The template generates a cd my-hono-api ``` -## 2. Update the starter query helpers - -Model access is namespace-qualified on PostgreSQL (`db.orm.public.User`), and the current template's helper files still use the older flat form, which fails at runtime. Open `src/prisma/users.ts` and `src/prisma/seed.ts` and change every `db.orm.User` to `db.orm.public.User`: - -```ts title="src/prisma/users.ts" -const users = await db.orm.public.User - .select("id", "email", "username", "name", "createdAt") - .take(limit) - .all(); -``` - -:::note - -This is a known template issue and will disappear from this guide once the template is updated. - -::: - -## 3. Initialize and seed the database +## 2. Initialize and seed the database ```bash bun run db:init @@ -59,7 +42,13 @@ bun run db:seed Seeded 3 users. ``` -## 4. Run the server +:::note + +Scaffolded with an older `create-prisma` and seeing `Cannot read properties of undefined (reading 'where')`? Update `db.orm.User` to `db.orm.public.User` in `src/prisma/seed.ts` and `src/prisma/users.ts`. Current templates generate the qualified form. + +::: + +## 3. Run the server ```bash bun run dev @@ -81,7 +70,7 @@ curl http://localhost:3000/users The route handler is ordinary Hono code calling an ordinary Prisma Next query; there is no framework adapter in between. -## 5. Add a POST route +## 4. Add a POST route Add a route that creates a user from the request body. Add this to `src/index.ts` above the `serve(...)` call: diff --git a/apps/docs/content/docs/guides/next/runtimes/bun.mdx b/apps/docs/content/docs/guides/next/runtimes/bun.mdx index e4b25c30af..5ed49b4ca2 100644 --- a/apps/docs/content/docs/guides/next/runtimes/bun.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/bun.mdx @@ -84,14 +84,6 @@ there are now 2 users That is the whole loop: schema to contract, contract to database, typed queries against both. -## Common gotchas - -:::warning - -The starter `seed.ts` and `users.ts` files in some templates still address models with the older flat form (`db.orm.User`), which fails at runtime with `Cannot read properties of undefined`. If you use them, change the model access to `db.orm.public.User`. - -::: - ## Prompt your coding agent The scaffold installs Prisma Next skills for your coding agent. Prompts that map to this guide: From 1d9868df4d4d57c59f49bdc08e4f2b8b65c006d3 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 7 Jul 2026 12:43:02 +0200 Subject: [PATCH 4/5] docs(guides): all framework templates tested and converted, latest-style 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 --- .../docs/guides/next/frameworks/astro.mdx | 72 ++++++++++++++++ .../docs/guides/next/frameworks/elysia.mdx | 3 +- .../docs/guides/next/frameworks/hono.mdx | 3 +- .../docs/guides/next/frameworks/meta.json | 11 ++- .../docs/guides/next/frameworks/nestjs.mdx | 82 +++++++++++++++++++ .../docs/guides/next/frameworks/nextjs.mdx | 72 ++++++++++++++++ .../docs/guides/next/frameworks/nuxt.mdx | 72 ++++++++++++++++ .../docs/guides/next/frameworks/sveltekit.mdx | 72 ++++++++++++++++ .../guides/next/frameworks/tanstack-start.mdx | 72 ++++++++++++++++ apps/docs/content/docs/guides/next/index.mdx | 54 +++++++----- .../content/docs/guides/next/runtimes/bun.mdx | 3 +- .../docs/guides/next/runtimes/deno.mdx | 3 +- apps/docs/next.config.mjs | 6 ++ 13 files changed, 494 insertions(+), 31 deletions(-) create mode 100644 apps/docs/content/docs/guides/next/frameworks/astro.mdx create mode 100644 apps/docs/content/docs/guides/next/frameworks/nestjs.mdx create mode 100644 apps/docs/content/docs/guides/next/frameworks/nextjs.mdx create mode 100644 apps/docs/content/docs/guides/next/frameworks/nuxt.mdx create mode 100644 apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx create mode 100644 apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx diff --git a/apps/docs/content/docs/guides/next/frameworks/astro.mdx b/apps/docs/content/docs/guides/next/frameworks/astro.mdx new file mode 100644 index 0000000000..a582e3249c --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/astro.mdx @@ -0,0 +1,72 @@ +--- +title: Astro +description: Set up Prisma Next in a Astro app with create-prisma, from scaffold to rendered data. +url: /guides/next/frameworks/astro +metaTitle: How to use Prisma Next with Astro +metaDescription: Scaffold a Astro project with Prisma Next and Prisma Postgres, initialize the database, seed it, and see your data, with tested commands. +--- + +## Introduction + +This guide shows you how to use Prisma Next in an Astro site. You scaffold a project that queries users during server rendering and exposes a JSON API route, initialize the schema, and see your data render. + +Every command below was run end to end against a live [Prisma Postgres](/postgres) database. + +## Quick start + +One command scaffolds the project with Prisma Next wired in: + +```npm +npx create-prisma@next --template astro --provider postgres +``` + +Pick Prisma Postgres at the database prompt to have a database created for you, or paste your own `DATABASE_URL`. + +## Prerequisites + +- [Node.js](https://nodejs.org) v20.19 or later +- A PostgreSQL connection string, or nothing at all: the scaffold can create the database for you + +## 1. Scaffold and enter the project + +```npm +npx create-prisma@next --template astro --provider postgres +cd my-app +``` + +The scaffold writes your connection string to `.env`, generates the Astro app with Prisma Next wired in, installs dependencies, and emits the contract your queries are type-checked against. + +## 2. Initialize and seed the database + +```npm +npm run db:init +npm run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +`db:init` applies your schema (`src/prisma/contract.prisma`) to the database and signs it; the seed gives the first page something to show. + +## 3. Run and verify + +```npm +npm run dev +``` + +Open [http://localhost:4321](http://localhost:4321). The page lists the seeded users; `GET /api/users` returns them as JSON. + +## Where things live + +- `src/pages/index.astro`: queries users in the frontmatter and renders them +- `src/pages/api/users.ts`: a JSON API route backed by the same query +- `src/prisma/db.ts`: the Prisma Next client both import + +Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Prisma Next overview](/orm/next) covers the contract-first model behind it. + +## Next steps + +- Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx index 2dbc933342..30170eece7 100644 --- a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx @@ -1,10 +1,9 @@ --- -title: How to use Prisma Next with Elysia +title: Elysia description: Build an Elysia API on Prisma Next with the elysia template. url: /guides/next/frameworks/elysia metaTitle: How to use Prisma Next with Elysia metaDescription: Scaffold an Elysia API backed by Prisma Next and Prisma Postgres, seed it, and serve users over HTTP, with tested commands and output. -badge: early-access --- ## Introduction diff --git a/apps/docs/content/docs/guides/next/frameworks/hono.mdx b/apps/docs/content/docs/guides/next/frameworks/hono.mdx index 19fc7a8dbe..b2e5b38f7d 100644 --- a/apps/docs/content/docs/guides/next/frameworks/hono.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/hono.mdx @@ -1,10 +1,9 @@ --- -title: How to use Prisma Next with Hono +title: Hono description: Build a Hono API on Prisma Next with the hono template, then add your own routes. url: /guides/next/frameworks/hono metaTitle: How to use Prisma Next with Hono metaDescription: Scaffold a Hono API backed by Prisma Next and Prisma Postgres, seed it, serve users over HTTP, and add a POST route, with tested commands and output. -badge: early-access --- ## Introduction diff --git a/apps/docs/content/docs/guides/next/frameworks/meta.json b/apps/docs/content/docs/guides/next/frameworks/meta.json index e8080c5f9f..bc44218fe6 100644 --- a/apps/docs/content/docs/guides/next/frameworks/meta.json +++ b/apps/docs/content/docs/guides/next/frameworks/meta.json @@ -1,5 +1,14 @@ { "title": "Frameworks", "defaultOpen": true, - "pages": ["hono", "elysia"] + "pages": [ + "nextjs", + "astro", + "nuxt", + "sveltekit", + "tanstack-start", + "nestjs", + "hono", + "elysia" + ] } diff --git a/apps/docs/content/docs/guides/next/frameworks/nestjs.mdx b/apps/docs/content/docs/guides/next/frameworks/nestjs.mdx new file mode 100644 index 0000000000..9c9d4738b2 --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/nestjs.mdx @@ -0,0 +1,82 @@ +--- +title: NestJS +description: Set up Prisma Next in a NestJS app with create-prisma, from scaffold to rendered data. +url: /guides/next/frameworks/nestjs +metaTitle: How to use Prisma Next with NestJS +metaDescription: Scaffold a NestJS project with Prisma Next and Prisma Postgres, initialize the database, seed it, and see your data, with tested commands. +--- + +## Introduction + +This guide shows you how to use Prisma Next in a NestJS API. You scaffold a project with a users controller backed by Prisma Next, initialize the schema, and query it over HTTP. + +Every command below was run end to end against a live [Prisma Postgres](/postgres) database. + +## Quick start + +One command scaffolds the project with Prisma Next wired in: + +```npm +npx create-prisma@next --template nest --provider postgres +``` + +Pick Prisma Postgres at the database prompt to have a database created for you, or paste your own `DATABASE_URL`. + +## Prerequisites + +- [Node.js](https://nodejs.org) v20.19 or later +- A PostgreSQL connection string, or nothing at all: the scaffold can create the database for you + +## 1. Scaffold and enter the project + +```npm +npx create-prisma@next --template nest --provider postgres +cd my-app +``` + +The scaffold writes your connection string to `.env`, generates the NestJS app with Prisma Next wired in, installs dependencies, and emits the contract your queries are type-checked against. + +## 2. Initialize and seed the database + +```npm +npm run db:init +npm run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +`db:init` applies your schema (`src/prisma/contract.prisma`) to the database and signs it; the seed gives the first page something to show. + +## 3. Run and verify + +```npm +npm run dev +``` + +Query the API: + +```bash +curl http://localhost:3000/users +``` + +```json no-copy +[ + { "id": "1", "email": "alice@prisma.io", "username": "alice", "name": "Alice", "createdAt": "2026-07-07T09:44:19.201Z" } +] +``` + +## Where things live + +- `src/users.controller.ts`: the `GET /users` route +- `src/users.service.ts`: the service that runs the Prisma Next query +- `src/prisma/db.ts`: the Prisma Next client the service imports + +Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Prisma Next overview](/orm/next) covers the contract-first model behind it. + +## Next steps + +- Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/nextjs.mdx b/apps/docs/content/docs/guides/next/frameworks/nextjs.mdx new file mode 100644 index 0000000000..eee05f184b --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/nextjs.mdx @@ -0,0 +1,72 @@ +--- +title: Next.js +description: Set up Prisma Next in a Next.js app with create-prisma, from scaffold to rendered data. +url: /guides/next/frameworks/nextjs +metaTitle: How to use Prisma Next with Next.js +metaDescription: Scaffold a Next.js project with Prisma Next and Prisma Postgres, initialize the database, seed it, and see your data, with tested commands. +--- + +## Introduction + +This guide shows you how to use Prisma Next in a Next.js app. You scaffold a project where a server component queries your database, initialize the schema, and see your data render. + +Every command below was run end to end against a live [Prisma Postgres](/postgres) database. + +## Quick start + +One command scaffolds the project with Prisma Next wired in: + +```npm +npx create-prisma@next --template next --provider postgres +``` + +Pick Prisma Postgres at the database prompt to have a database created for you, or paste your own `DATABASE_URL`. + +## Prerequisites + +- [Node.js](https://nodejs.org) v20.19 or later +- A PostgreSQL connection string, or nothing at all: the scaffold can create the database for you + +## 1. Scaffold and enter the project + +```npm +npx create-prisma@next --template next --provider postgres +cd my-app +``` + +The scaffold writes your connection string to `.env`, generates the Next.js app with Prisma Next wired in, installs dependencies, and emits the contract your queries are type-checked against. + +## 2. Initialize and seed the database + +```npm +npm run db:init +npm run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +`db:init` applies your schema (`src/prisma/contract.prisma`) to the database and signs it; the seed gives the first page something to show. + +## 3. Run and verify + +```npm +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000). The page lists the seeded users, rendered by a server component that calls Prisma Next directly. + +## Where things live + +- `src/app/page.tsx`: a server component that queries users and renders them +- `src/prisma/db.ts`: the Prisma Next client your components import +- `src/prisma/contract.prisma`: your schema + +Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Prisma Next overview](/orm/next) covers the contract-first model behind it. + +## Next steps + +- Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/nuxt.mdx b/apps/docs/content/docs/guides/next/frameworks/nuxt.mdx new file mode 100644 index 0000000000..05ed8229e3 --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/nuxt.mdx @@ -0,0 +1,72 @@ +--- +title: Nuxt +description: Set up Prisma Next in a Nuxt app with create-prisma, from scaffold to rendered data. +url: /guides/next/frameworks/nuxt +metaTitle: How to use Prisma Next with Nuxt +metaDescription: Scaffold a Nuxt project with Prisma Next and Prisma Postgres, initialize the database, seed it, and see your data, with tested commands. +--- + +## Introduction + +This guide shows you how to use Prisma Next in a Nuxt app. You scaffold a project where a server API route queries your database and the page renders it, initialize the schema, and see your data. + +Every command below was run end to end against a live [Prisma Postgres](/postgres) database. + +## Quick start + +One command scaffolds the project with Prisma Next wired in: + +```npm +npx create-prisma@next --template nuxt --provider postgres +``` + +Pick Prisma Postgres at the database prompt to have a database created for you, or paste your own `DATABASE_URL`. + +## Prerequisites + +- [Node.js](https://nodejs.org) v20.19 or later +- A PostgreSQL connection string, or nothing at all: the scaffold can create the database for you + +## 1. Scaffold and enter the project + +```npm +npx create-prisma@next --template nuxt --provider postgres +cd my-app +``` + +The scaffold writes your connection string to `.env`, generates the Nuxt app with Prisma Next wired in, installs dependencies, and emits the contract your queries are type-checked against. + +## 2. Initialize and seed the database + +```npm +npm run db:init +npm run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +`db:init` applies your schema (`src/prisma/contract.prisma`) to the database and signs it; the seed gives the first page something to show. + +## 3. Run and verify + +```npm +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000). The page lists the seeded users, fetched from the `/api/users` server route. + +## Where things live + +- `server/api/users.get.ts`: the server route that queries users +- `app/pages/index.vue`: the page that fetches and renders them +- `src/prisma/db.ts`: the Prisma Next client the server route imports + +Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Prisma Next overview](/orm/next) covers the contract-first model behind it. + +## Next steps + +- Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx b/apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx new file mode 100644 index 0000000000..1996ec4683 --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx @@ -0,0 +1,72 @@ +--- +title: SvelteKit +description: Set up Prisma Next in a SvelteKit app with create-prisma, from scaffold to rendered data. +url: /guides/next/frameworks/sveltekit +metaTitle: How to use Prisma Next with SvelteKit +metaDescription: Scaffold a SvelteKit project with Prisma Next and Prisma Postgres, initialize the database, seed it, and see your data, with tested commands. +--- + +## Introduction + +This guide shows you how to use Prisma Next in a SvelteKit app. You scaffold a project where a server load function queries your database, initialize the schema, and see your data render. + +Every command below was run end to end against a live [Prisma Postgres](/postgres) database. + +## Quick start + +One command scaffolds the project with Prisma Next wired in: + +```npm +npx create-prisma@next --template svelte --provider postgres +``` + +Pick Prisma Postgres at the database prompt to have a database created for you, or paste your own `DATABASE_URL`. + +## Prerequisites + +- [Node.js](https://nodejs.org) v20.19 or later +- A PostgreSQL connection string, or nothing at all: the scaffold can create the database for you + +## 1. Scaffold and enter the project + +```npm +npx create-prisma@next --template svelte --provider postgres +cd my-app +``` + +The scaffold writes your connection string to `.env`, generates the SvelteKit app with Prisma Next wired in, installs dependencies, and emits the contract your queries are type-checked against. + +## 2. Initialize and seed the database + +```npm +npm run db:init +npm run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +`db:init` applies your schema (`src/prisma/contract.prisma`) to the database and signs it; the seed gives the first page something to show. + +## 3. Run and verify + +```npm +npm run dev +``` + +Open [http://localhost:5173](http://localhost:5173). The page lists the seeded users, loaded on the server by the `+page.server.ts` load function. + +## Where things live + +- `src/routes/+page.server.ts`: the server `load` function that queries users +- `src/routes/+page.svelte`: the page that renders them +- `src/prisma/db.ts`: the Prisma Next client the load function imports + +Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Prisma Next overview](/orm/next) covers the contract-first model behind it. + +## Next steps + +- Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx b/apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx new file mode 100644 index 0000000000..e2c81c99bf --- /dev/null +++ b/apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx @@ -0,0 +1,72 @@ +--- +title: TanStack Start +description: Set up Prisma Next in a TanStack Start app with create-prisma, from scaffold to rendered data. +url: /guides/next/frameworks/tanstack-start +metaTitle: How to use Prisma Next with TanStack Start +metaDescription: Scaffold a TanStack Start project with Prisma Next and Prisma Postgres, initialize the database, seed it, and see your data, with tested commands. +--- + +## Introduction + +This guide shows you how to use Prisma Next in a TanStack Start app. You scaffold a project where a server function queries your database and a route loader feeds it to the page, initialize the schema, and see your data. + +Every command below was run end to end against a live [Prisma Postgres](/postgres) database. + +## Quick start + +One command scaffolds the project with Prisma Next wired in: + +```npm +npx create-prisma@next --template tanstack-start --provider postgres +``` + +Pick Prisma Postgres at the database prompt to have a database created for you, or paste your own `DATABASE_URL`. + +## Prerequisites + +- [Node.js](https://nodejs.org) v20.19 or later +- A PostgreSQL connection string, or nothing at all: the scaffold can create the database for you + +## 1. Scaffold and enter the project + +```npm +npx create-prisma@next --template tanstack-start --provider postgres +cd my-app +``` + +The scaffold writes your connection string to `.env`, generates the TanStack Start app with Prisma Next wired in, installs dependencies, and emits the contract your queries are type-checked against. + +## 2. Initialize and seed the database + +```npm +npm run db:init +npm run db:seed +``` + +```text no-copy +"summary": "Applied 5 operation(s) across 1 space(s), database signed" +Seeded 3 users. +``` + +`db:init` applies your schema (`src/prisma/contract.prisma`) to the database and signs it; the seed gives the first page something to show. + +## 3. Run and verify + +```npm +npm run dev +``` + +Open [http://localhost:3000](http://localhost:3000). The page lists the seeded users, provided by the route loader's server function. + +## Where things live + +- `src/routes/index.tsx`: the route: a `createServerFn` queries users, the loader passes them to the page +- `src/prisma/users.ts`: the query helper the server function calls +- `src/prisma/db.ts`: the Prisma Next client behind it + +Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Prisma Next overview](/orm/next) covers the contract-first model behind it. + +## Next steps + +- Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/index.mdx b/apps/docs/content/docs/guides/next/index.mdx index 9a13e729b5..7a7d5ebf72 100644 --- a/apps/docs/content/docs/guides/next/index.mdx +++ b/apps/docs/content/docs/guides/next/index.mdx @@ -1,39 +1,49 @@ --- -title: Prisma Next guides -description: Start-to-finish guides for building with Prisma Next, converted from the Prisma 7 guides as each one is tested. +title: Overview +description: Practical, step-by-step guides for building with Prisma Next, each one run end to end before it ships. url: /guides/next metaTitle: Prisma Next guides -metaDescription: Hands-on Prisma Next guides for runtimes and frameworks, with tested examples. More groups land incrementally, including deployment, testing, and migration. -badge: early-access +metaDescription: Hands-on Prisma Next guides for frameworks and runtimes, with tested examples. More categories land incrementally, including migration, deployment, and testing. --- -These guides take you from an empty directory to a working result with Prisma Next. They mirror the structure of the [Prisma 7 guides](/guides): the same folders, converted one guide at a time, and only after every command in a guide was run end to end against a live database. +Practical, step-by-step guides for building with Prisma Next. They mirror the structure of the [Prisma 7 guides](/guides), and every command in a published guide was run end to end against a live database before it landed here. -Use the version dropdown in the sidebar to switch between these guides and the Prisma 7 guides. The Prisma 7 versions stay where they are until Prisma Next becomes the default. +Use the version dropdown in the sidebar to switch between these guides and the Prisma 7 guides. -## Available now +## Frameworks + +Each framework guide scaffolds a working app with `create-prisma`, initializes the database, and ends with your data rendering: + + + + + + + + + + + + +## Runtimes - }> - Scaffold a Prisma Next app with Bun, initialize Prisma Postgres, and run your first typed query. - - }> - Run Prisma Next on Deno, including the import and permission differences that matter. - - }> - Build a Hono API on Prisma Next with the hono template, and add your own routes. - + + ## Coming as they land -The guide groups follow the [Prisma Next docs plan](https://linear.app/prisma-company/issue/DR-8689/docs-guides-incremental-migration-deployment-performance-testing) and land one at a time, each tested before it ships: +The remaining categories follow the [Prisma Next docs plan](https://linear.app/prisma-company/issue/DR-8689/docs-guides-incremental-migration-deployment-performance-testing) and land one guide at a time, each tested before it ships: -- Migration: moving from Prisma 7, and between Prisma Next releases -- Deployment: Vercel, Fly.io, AWS Lambda, Cloudflare Workers, Docker -- Frameworks: Next.js, NestJS, SvelteKit, Astro, Nuxt, TanStack Start, Elysia -- Testing: unit tests, integration tests, testing against the contract -- Patterns, performance, and operations +- **Migration**: moving from Prisma 7, and between Prisma Next releases +- **Deployment**: Vercel, Fly.io, AWS Lambda, Cloudflare Workers, Docker +- **Extensions**: using pgvector, using ParadeDB, building your own +- **Databases**: PostgreSQL tips, MongoDB tips, adding a new database +- **Patterns**: multi-tenant apps, soft deletes, audit logs, pagination at scale +- **Performance**: query limits in CI, reading query plans, indexing +- **Testing**: unit tests, integration tests, testing against the contract +- **Operations**: connection management, backups, health checks, zero-downtime migrations Until a Prisma Next guide exists for your topic, the [Prisma 7 guide](/guides) still applies to Prisma 7 projects, and the [Prisma Next overview](/orm/next) covers the concepts any guide builds on. diff --git a/apps/docs/content/docs/guides/next/runtimes/bun.mdx b/apps/docs/content/docs/guides/next/runtimes/bun.mdx index 5ed49b4ca2..05f73cdb4d 100644 --- a/apps/docs/content/docs/guides/next/runtimes/bun.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/bun.mdx @@ -1,10 +1,9 @@ --- -title: How to use Prisma Next with Bun +title: Bun description: Scaffold a Prisma Next app with Bun, initialize your database, and run your first typed query. url: /guides/next/runtimes/bun metaTitle: How to use Prisma Next with Bun metaDescription: Set up a Prisma Next project with Bun and Prisma Postgres, from scaffold to first query, with tested commands and real output. -badge: early-access --- ## Introduction diff --git a/apps/docs/content/docs/guides/next/runtimes/deno.mdx b/apps/docs/content/docs/guides/next/runtimes/deno.mdx index 864c7d04f3..da00288d48 100644 --- a/apps/docs/content/docs/guides/next/runtimes/deno.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/deno.mdx @@ -1,10 +1,9 @@ --- -title: How to use Prisma Next with Deno +title: Deno description: Run Prisma Next on Deno, including the import-extension and permission differences that matter. url: /guides/next/runtimes/deno metaTitle: How to use Prisma Next with Deno metaDescription: Set up a Prisma Next project on Deno with Prisma Postgres, from scaffold to first query, with tested commands and real output. -badge: early-access --- ## Introduction diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs index 01ff33317e..aa6b572f4f 100644 --- a/apps/docs/next.config.mjs +++ b/apps/docs/next.config.mjs @@ -314,6 +314,12 @@ const config = { // have a Prisma Next replacement; unconverted guides keep their URL): // { source: "/guides/runtimes/bun", destination: "/guides/v7/runtimes/bun", permanent: false }, // { source: "/guides/runtimes/deno", destination: "/guides/v7/runtimes/deno", permanent: false }, + // { source: "/guides/frameworks/nextjs", destination: "/guides/v7/frameworks/nextjs", permanent: false }, + // { source: "/guides/frameworks/astro", destination: "/guides/v7/frameworks/astro", permanent: false }, + // { source: "/guides/frameworks/nuxt", destination: "/guides/v7/frameworks/nuxt", permanent: false }, + // { source: "/guides/frameworks/sveltekit", destination: "/guides/v7/frameworks/sveltekit", permanent: false }, + // { source: "/guides/frameworks/tanstack-start", destination: "/guides/v7/frameworks/tanstack-start", permanent: false }, + // { source: "/guides/frameworks/nestjs", destination: "/guides/v7/frameworks/nestjs", permanent: false }, // { source: "/guides/frameworks/hono", destination: "/guides/v7/frameworks/hono", permanent: false }, // { source: "/guides/frameworks/elysia", destination: "/guides/v7/frameworks/elysia", permanent: false }, // From 92a34f3e3209a5d0025fe972afddaf0300d18859 Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 7 Jul 2026 12:52:11 +0200 Subject: [PATCH 5/5] docs(guides): cross-link the merged Fundamentals section; clarify migration 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 --- apps/docs/content/docs/guides/next/frameworks/astro.mdx | 1 + apps/docs/content/docs/guides/next/frameworks/elysia.mdx | 1 + apps/docs/content/docs/guides/next/frameworks/hono.mdx | 3 ++- apps/docs/content/docs/guides/next/frameworks/nestjs.mdx | 1 + apps/docs/content/docs/guides/next/frameworks/nextjs.mdx | 1 + apps/docs/content/docs/guides/next/frameworks/nuxt.mdx | 1 + apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx | 1 + .../content/docs/guides/next/frameworks/tanstack-start.mdx | 1 + apps/docs/content/docs/guides/next/index.mdx | 6 ++++-- apps/docs/content/docs/guides/next/runtimes/bun.mdx | 1 + apps/docs/content/docs/guides/next/runtimes/deno.mdx | 1 + 11 files changed, 15 insertions(+), 3 deletions(-) diff --git a/apps/docs/content/docs/guides/next/frameworks/astro.mdx b/apps/docs/content/docs/guides/next/frameworks/astro.mdx index a582e3249c..7b6526e9d3 100644 --- a/apps/docs/content/docs/guides/next/frameworks/astro.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/astro.mdx @@ -69,4 +69,5 @@ Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Pr ## Next steps - Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx index 30170eece7..f3dfa4c195 100644 --- a/apps/docs/content/docs/guides/next/frameworks/elysia.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/elysia.mdx @@ -86,5 +86,6 @@ The scaffold installs Prisma Next skills for your coding agent. Prompts that map ## Next steps +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. - [Use the Hono guide](/guides/next/frameworks/hono) for the tested POST route pattern. diff --git a/apps/docs/content/docs/guides/next/frameworks/hono.mdx b/apps/docs/content/docs/guides/next/frameworks/hono.mdx index b2e5b38f7d..e7623d4268 100644 --- a/apps/docs/content/docs/guides/next/frameworks/hono.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/hono.mdx @@ -113,8 +113,9 @@ The scaffold installs Prisma Next skills for your coding agent. Prompts that map - "Using the prisma-next-queries skill, add GET /users/:id that returns one user or a 404." - "Add a Post model related to User, update the database, and expose GET /users/:id/posts." -- "Wrap the signup route's writes in a transaction." +- "Wrap the signup route's writes in a [transaction](/orm/next/fundamentals/transactions)." ## Next steps +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/nestjs.mdx b/apps/docs/content/docs/guides/next/frameworks/nestjs.mdx index 9c9d4738b2..bae676e1d6 100644 --- a/apps/docs/content/docs/guides/next/frameworks/nestjs.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/nestjs.mdx @@ -79,4 +79,5 @@ Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Pr ## Next steps - Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/nextjs.mdx b/apps/docs/content/docs/guides/next/frameworks/nextjs.mdx index eee05f184b..d51a7a7b26 100644 --- a/apps/docs/content/docs/guides/next/frameworks/nextjs.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/nextjs.mdx @@ -69,4 +69,5 @@ Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Pr ## Next steps - Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/nuxt.mdx b/apps/docs/content/docs/guides/next/frameworks/nuxt.mdx index 05ed8229e3..8b1fd1815b 100644 --- a/apps/docs/content/docs/guides/next/frameworks/nuxt.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/nuxt.mdx @@ -69,4 +69,5 @@ Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Pr ## Next steps - Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx b/apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx index 1996ec4683..e28ca489cc 100644 --- a/apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/sveltekit.mdx @@ -69,4 +69,5 @@ Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Pr ## Next steps - Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx b/apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx index e2c81c99bf..8be51d4a64 100644 --- a/apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx +++ b/apps/docs/content/docs/guides/next/frameworks/tanstack-start.mdx @@ -69,4 +69,5 @@ Model access is namespace-qualified on PostgreSQL: `db.orm.public.User`. The [Pr ## Next steps - Change the schema in `src/prisma/contract.prisma`, then run `npm run contract:emit` and `npm run db:update`. +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/index.mdx b/apps/docs/content/docs/guides/next/index.mdx index 7a7d5ebf72..fd9af46f11 100644 --- a/apps/docs/content/docs/guides/next/index.mdx +++ b/apps/docs/content/docs/guides/next/index.mdx @@ -36,7 +36,8 @@ Each framework guide scaffolds a working app with `create-prisma`, initializes t The remaining categories follow the [Prisma Next docs plan](https://linear.app/prisma-company/issue/DR-8689/docs-guides-incremental-migration-deployment-performance-testing) and land one guide at a time, each tested before it ships: -- **Migration**: moving from Prisma 7, and between Prisma Next releases +- **Upgrading**: moving from Prisma 7, and between Prisma Next releases +- **Migrations**: down migrations, handling schema conflicts, and working with the migration graph - **Deployment**: Vercel, Fly.io, AWS Lambda, Cloudflare Workers, Docker - **Extensions**: using pgvector, using ParadeDB, building your own - **Databases**: PostgreSQL tips, MongoDB tips, adding a new database @@ -45,9 +46,10 @@ The remaining categories follow the [Prisma Next docs plan](https://linear.app/p - **Testing**: unit tests, integration tests, testing against the contract - **Operations**: connection management, backups, health checks, zero-downtime migrations -Until a Prisma Next guide exists for your topic, the [Prisma 7 guide](/guides) still applies to Prisma 7 projects, and the [Prisma Next overview](/orm/next) covers the concepts any guide builds on. +Until a Prisma Next guide exists for your topic, the [Prisma 7 guide](/guides) still applies to Prisma 7 projects, and the [Fundamentals section](/orm/next/fundamentals/reading-data) covers the query patterns any guide builds on. ## Next steps - [Start with the quickstart](/next/quickstart/postgresql) if you don't have a Prisma Next project yet. +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): reading, writing, relations, transactions, and advanced queries. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts, typed queries, and migrations. diff --git a/apps/docs/content/docs/guides/next/runtimes/bun.mdx b/apps/docs/content/docs/guides/next/runtimes/bun.mdx index 05f73cdb4d..a5a7fe90e2 100644 --- a/apps/docs/content/docs/guides/next/runtimes/bun.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/bun.mdx @@ -92,4 +92,5 @@ The scaffold installs Prisma Next skills for your coding agent. Prompts that map ## Next steps +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. diff --git a/apps/docs/content/docs/guides/next/runtimes/deno.mdx b/apps/docs/content/docs/guides/next/runtimes/deno.mdx index da00288d48..be0aa9e9c2 100644 --- a/apps/docs/content/docs/guides/next/runtimes/deno.mdx +++ b/apps/docs/content/docs/guides/next/runtimes/deno.mdx @@ -93,5 +93,6 @@ The scaffold installs Prisma Next skills for your coding agent. Prompts that map ## Next steps +- [Learn the fundamentals](/orm/next/fundamentals/reading-data): filtering, sorting, pagination, and writes. - [Read the Prisma Next overview](/orm/next) for the concepts behind contracts and typed queries. - [Use the Bun guide](/guides/next/runtimes/bun) if you also target Bun; the flow is the same apart from the runtime differences above.