docs(guides): Prisma Next guides with a Guides version dropdown (DR-8689)

apps/docs/content/docs/guides/meta.json

@@ -4,6 +4,7 @@
   "icon": "NotebookTabs",
   "pages": [
     "index",
+    "next",
     "frameworks",
     "runtimes",
     "deployment",

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.

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.

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.

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
+
+<Cards>
+  <Card href="/guides/next/bun" title="Bun" icon={<Zap className="text-primary" />}>
+    Scaffold a Prisma Next app with Bun, initialize Prisma Postgres, and run your first typed query.
+  </Card>
+  <Card href="/guides/next/deno" title="Deno" icon={<Terminal className="text-primary" />}>
+    Run Prisma Next on Deno, including the import and permission differences that matter.
+  </Card>
+  <Card href="/guides/next/hono" title="Hono" icon={<Flame className="text-primary" />}>
+    Build a Hono API on Prisma Next with the hono template, and add your own routes.
+  </Card>
+</Cards>
+
+## 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.