# Writing guides (/docs/guides/making-guides)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

How to write, validate, and file a Prisma ORM guide for the Prisma documentation.

Location: Guides > Writing guides

## Introduction [#introduction]

This page is for people writing guides in this section. It covers the required structure, the formatting conventions, the validation rule every guide must pass, and how a guide's Prisma ORM 7 twin is versioned.

The short version: a guide is a walkthrough you ran end to end before publishing, written for Prisma ORM, with every command shown alongside the real output it produced.

## Prerequisites [#prerequisites]

* A clear understanding of the topic you are writing about
* Access to the Prisma documentation repository
* Familiarity with Markdown and MDX
* Node.js 24 or later and a PostgreSQL database to validate against (a local server or `npx create-db@latest`)

## The validation rule [#the-validation-rule]

Every command, file, and code block in a published guide was run by its author against a live database before it landed. Outputs shown in the guide are pasted from that run, trimmed for noise. If a step could not be run (a platform account you do not have, a paid service), the guide says so in the step and does not show output for it.

Two reference guides show the finished shape. Read them before writing:

* [Hono](https://www.prisma.io/docs/guides/frameworks/hono): a new project scaffolded with `create-prisma`, deployed to Prisma Compute.
* [Add Prisma ORM to an existing PostgreSQL database](https://www.prisma.io/docs/prisma-orm/add-to-existing-project/postgresql): the `orm init` and `contract infer` path for an app that already exists.

## Guide structure [#guide-structure]

### Required frontmatter [#required-frontmatter]

```mdx
---
title: '[Descriptive title]'
description: '[One sentence: what the reader builds or accomplishes]'
url: /guides/[category]/[slug]
metaTitle: How to use Prisma ORM with [Topic]
metaDescription: '[One sentence for search results]'
---
```

* `title`: a short, descriptive title in sentence case (for example "Docker", "Multiple databases", "GitHub Actions")
* `description`: one sentence describing what the reader accomplishes
* `url`: the page path under `content/docs` without the extension; the build derives the URL from the file path, and this field must match it
* `metaTitle` and `metaDescription`: the title and description for search engines
* `image`: a header image for social sharing, only if one exists at `/img/guides/`

### Required sections [#required-sections]

1. **Introduction** (`## Introduction`): what the guide builds, in two or three sentences, followed by the `Using Prisma ORM 7?` note (see [Versioning](#versioning-the-prisma-7-twin)).
2. **Prerequisites** (`## Prerequisites`): Node.js 24 or later, a database connection string or `npx create-db@latest`, and any accounts the guide needs. Keep it to what is truly necessary.
3. **Numbered steps** (`## 1. Scaffold the project`, `## 2. Initialize the database`, and so on): each step is one bounded action with its command, its real output in a `no-copy` block, and one or two sentences on what happened.
4. **Common gotchas** (`## Common gotchas`): the failures you hit while validating, with the verbatim error text and the fix.
5. **Use with your agent** (`## Use with your agent`): this section comes after the steps, so a reader sees the instructions for a person first. It has three parts, in this order. First, an `<AgentPrompt>` block with a numbered prompt a coding agent can follow to complete the guide. Reference the guide's own `.md` URL (`https://www.prisma.io/docs/guides/[category]/[slug].md`) so the agent can read it. Second, a pointer to `npx prisma@latest init` for the [Prisma ORM skills](https://www.prisma.io/docs/ai/tools/skills). Third, two or three follow-up prompts that map to the guide.
6. **Next steps** (`## Next steps`): links to the fundamentals and the related Prisma ORM pages.

## Writing style and voice [#writing-style-and-voice]

* Write direct instructional prose: say what to do, show the command, show the output.
* Use active voice and present tense, and address the reader as "you".
* Keep sentences short. One idea per sentence.
* Do not use em dashes anywhere, including code comments. Use a period, a comma, or a colon.
* Explain a removed Prisma ORM 7 step in one sentence only where a reader coming from Prisma ORM 7 would look for it (for example, "There is no `prisma generate` step; the runtime reads the emitted contract.").
* Do not describe Prisma ORM 8 as a preview or as not production ready, and do not mention release candidate numbers. Prisma ORM 8 is the current release; Prisma ORM 7 remains supported.

### Code examples [#code-examples]

* Every code block is complete and was run as shown.
* Use `title=` on file blocks: ` ```ts title="src/prisma/db.ts" `.
* Use ` ```npm ` for package manager commands (the UI converts them to pnpm, yarn, and bun).
* Use ` ```bash ` for other shell commands and for `.env` files, so `# [!code ++]` and `# [!code --]` annotations render.
* Use ` ```text no-copy ` and ` ```json no-copy ` for captured output.
* Use ` ```prisma ` for contract files, ` ```typescript ` or ` ```ts ` for TypeScript, ` ```json ` for JSON.
* Use `// [!code ++]`, `// [!code --]`, and `// [!code highlight]` to show changes inside a file.

### Formatting conventions [#formatting-conventions]

* Backticks for file names (`contract.prisma`), directories (`src/prisma/`), commands, and code elements (`db.orm.public.User`).
* Admonitions for asides:
  ```markdown
  :::note
  Important details to remember
  :::

  :::warning
  A gotcha that breaks the flow if missed
  :::

  :::tip
  A shortcut or best practice
  :::
  ```
* Never skip heading levels.
* Link Prisma ORM 8 pages with relative paths: `/orm/...`, `/cli/...`, `/prisma-orm/...`. Never link `/orm/v7/...` from a Prisma ORM 8 guide except in the `Using Prisma ORM 7?` note.

## Prisma ORM patterns [#prisma-orm-patterns]

### Versions in commands [#versions-in-commands]

Commands that run before the project has Prisma installed use the `@latest` tag, never a pinned version:

  

#### bun

```bash
bunx create-prisma@latest my-app --template hono --provider postgres --no-deploy
bunx prisma@latest orm init --target postgres
bunx --bun prisma@latest init
bunx create-db@latest
```

#### pnpm

```bash
pnpm dlx create-prisma@latest my-app --template hono --provider postgres --no-deploy
pnpm dlx prisma@latest orm init --target postgres
pnpm dlx prisma@latest init
pnpm dlx create-db@latest
```

#### yarn

```bash
yarn dlx create-prisma@latest my-app --template hono --provider postgres --no-deploy
yarn dlx prisma@latest orm init --target postgres
yarn dlx prisma@latest init
yarn dlx create-db@latest
```

#### npm

```bash
npx create-prisma@latest my-app --template hono --provider postgres --no-deploy
npx prisma@latest orm init --target postgres
npx prisma@latest init
npx create-db@latest
```

Every other command is `npx prisma <command>`, which runs the version the project has installed. In CI that is the version from the lockfile, and a reader never sees a guide behave differently from their own checkout. The docs' command tabs render `npx prisma` as `pnpm prisma` and `yarn prisma` for the same reason.

Package installs happen inside `create-prisma` and `orm init`; show their output rather than hand-written `npm install` lines with version numbers.

### New project [#new-project]

Scaffold with `create-prisma` and one of its templates (`minimal`, `hono`, `elysia`, `nest`, `next`, `svelte`, `astro`, `nuxt`, `tanstack-start`):

  

#### bun

```bash
bunx create-prisma@latest my-app --template next --provider postgres --no-deploy
```

#### pnpm

```bash
pnpm dlx create-prisma@latest my-app --template next --provider postgres --no-deploy
```

#### yarn

```bash
yarn dlx create-prisma@latest my-app --template next --provider postgres --no-deploy
```

#### npm

```bash
npx create-prisma@latest my-app --template next --provider postgres --no-deploy
```

The template ships the contract in `src/prisma/contract.prisma`, the runtime in `src/prisma/db.ts`, and package scripts for `contract:emit`, `db:init`, `db:update`, `migration:plan`, and `migrate`.

### Existing project [#existing-project]

Add Prisma ORM to an app that already exists:

  

#### bun

```bash
bunx prisma@latest orm init --target postgres
```

#### pnpm

```bash
pnpm dlx prisma@latest orm init --target postgres
```

#### yarn

```bash
yarn dlx prisma@latest orm init --target postgres
```

#### npm

```bash
npx prisma@latest orm init --target postgres
```

For a database that already has tables, follow with `npx prisma contract infer --output ./src/prisma/contract.prisma`, review the contract, then `contract emit` and `db sign`. Two things to check in the review: `orm init` keeps `"type": "commonjs"` if your `package.json` declares it and adds `"type": "module"` if there is no `"type"` field (a new project should use `"type": "module"`; an existing CommonJS app follows [In a CommonJS project](https://www.prisma.io/docs/cli/orm-init#in-a-commonjs-project)), and `contract infer` writes `Timestamptz` for timestamp columns while the runtime on Node.js needs `TimestamptzString`.

### Runtime instantiation [#runtime-instantiation]

Show the scaffolded `src/prisma/db.ts` rather than writing a client by hand:

```ts title="src/prisma/db.ts"
import "dotenv/config";
import postgres from "@prisma/orm-postgres/runtime";
import type { Contract } from "./contract.d";
import contractJson from "./contract.json" with { type: "json" };

export const db = postgres<Contract>({
  contractJson,
  url: process.env.DATABASE_URL!,
});
```

Queries name the PostgreSQL schema (`db.orm.public.User.select("id", "email").all()`). Close the client once on process shutdown with `await db.close()`, never per request; in a per-request environment such as Cloudflare Workers, create the client inside the handler instead (see [Cloudflare Workers](https://www.prisma.io/docs/guides/deployment/cloudflare-workers)).

### Database lifecycle [#database-lifecycle]

| Task                                       | Command                                   |
| ------------------------------------------ | ----------------------------------------- |
| First apply and sign                       | `npx prisma db init`                      |
| Check the database matches the contract    | `npx prisma db verify`                    |
| Apply a contract change during development | `npx prisma db update`                    |
| Plan a checked-in migration                | `npx prisma migration plan --name <name>` |
| Apply checked-in migrations                | `npx prisma db migrate`                   |

### Environment variables [#environment-variables]

Show `.env` files with ` ```bash title=".env" `:

```bash title=".env"
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
```

The CLI loads `.env` through `prisma.config.ts`. Scaffolded `db.ts` files import `dotenv/config`; `create-prisma` templates read the environment variable only, so tell the reader to export it in the shell.

## Versioning the Prisma ORM 7 twin [#versioning-the-prisma-7-twin]

The unversioned tree under `guides/` is Prisma ORM 8. Prisma ORM 7 guides live under `guides/v7/` with the same subpath, and the sidebar version dropdown switches between them.

When you port a Prisma ORM 7 guide:

1. Copy the Prisma ORM 7 file to `guides/v7/<same subpath>` and change only its `url:` to the `/guides/v7/...` path. Keep its Prisma ORM 7 pins.
2. Add the file to the matching `guides/v7/<category>/meta.json` and to the list on [/guides/v7](https://www.prisma.io/docs/guides/v7).
3. Write the Prisma ORM 8 guide over the original path.
4. Add this note right after the introduction of the Prisma ORM 8 guide:

```markdown
:::note[Using Prisma ORM 7?]

Prisma ORM 8 is the current release. Prisma ORM 7 remains fully supported; the Prisma ORM 7 version of this guide is at [/guides/v7/[category]/[slug]](/guides/v7/[category]/[slug]).

:::
```

If a topic cannot be ported because Prisma ORM 8 does not support it yet (for example Cloudflare D1, or a third-party adapter that requires Prisma Client), move the page under `guides/v7/`, change its `url:` frontmatter to the `/guides/v7/...` path (or re-run `npx tsx scripts/add-url-frontmatter.ts` in `apps/docs`; a stale `url:` fails silently and no linter catches it), add its filename to the matching `guides/v7/<category>/meta.json` and its link to `guides/v7/index.mdx` (a redirect alone leaves it out of the Prisma ORM 7 navigation), and add a redirect from the old URL in the live region of `redirects()` in `apps/docs/next.config.mjs`, near the `/llms/next.txt` entry (`apps/docs/vercel.json` holds the legacy redirects and the entries `pnpm generate:rest-api-docs` writes, not new page moves). Then run `pnpm run audit:redirects:strict` in `apps/docs`: it checks that every `vercel.json` destination still resolves, so it catches the legacy redirects whose destination just moved; it does not read `next.config.mjs`. Do not leave a Prisma ORM 7 page at a Prisma ORM 8 URL without a version marker.

## Guide categories [#guide-categories]

| Category            | Directory                      | Description                             | Examples                                                                                                                                                                        |
| ------------------- | ------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Framework**       | `guides/frameworks/`           | Integrate Prisma ORM with frameworks    | [Next.js](https://www.prisma.io/docs/guides/frameworks/nextjs), [Hono](https://www.prisma.io/docs/guides/frameworks/hono), [React Router](https://www.prisma.io/docs/guides/frameworks/react-router-7)                                                        |
| **Runtime**         | `guides/runtimes/`             | Run Prisma ORM on a runtime             | [Bun](https://www.prisma.io/docs/guides/runtimes/bun), [Deno](https://www.prisma.io/docs/guides/runtimes/deno)                                                                                                                      |
| **Deployment**      | `guides/deployment/`           | Deploy apps and set up monorepos        | [Docker](https://www.prisma.io/docs/guides/deployment/docker), [Cloudflare Workers](https://www.prisma.io/docs/guides/deployment/cloudflare-workers), [Turborepo](https://www.prisma.io/docs/guides/deployment/turborepo)                                     |
| **Integration**     | `guides/integrations/`         | Use Prisma ORM with platforms and tools | [GitHub Actions](https://www.prisma.io/docs/guides/integrations/github-actions), [AI SDK](https://www.prisma.io/docs/guides/integrations/ai-sdk)                                                                                    |
| **Database**        | `guides/database/`             | Database patterns and migrations        | [Multiple databases](https://www.prisma.io/docs/guides/database/multiple-databases), [Expand-and-contract migrations](https://www.prisma.io/docs/guides/database/data-migration), [Schema changes](https://www.prisma.io/docs/guides/database/schema-changes) |
| **Authentication**  | `guides/authentication/`       | Authentication patterns                 | [Clerk with Next.js](https://www.prisma.io/docs/guides/authentication/clerk/nextjs)                                                                                                                       |
| **Prisma Postgres** | `guides/postgres/`             | Prisma Postgres features                | [Vercel](https://www.prisma.io/docs/guides/postgres/vercel), [Netlify](https://www.prisma.io/docs/guides/postgres/netlify), [Viewing data](https://www.prisma.io/docs/guides/postgres/viewing-data)                                                           |
| **Migration**       | `guides/switch-to-prisma-orm/` | Switch from other ORMs                  | [From Drizzle](https://www.prisma.io/docs/guides/switch-to-prisma-orm/from-drizzle), [From Mongoose](https://www.prisma.io/docs/guides/switch-to-prisma-orm/from-mongoose)                                                          |
| **Upgrade**         | `guides/upgrade-prisma-orm/`   | Move between Prisma versions            | [Prisma ORM 7 to 8 on PostgreSQL](https://www.prisma.io/docs/guides/upgrade-prisma-orm/postgresql)                                                                                                        |

## Guide template [#guide-template]

Copy this template for a new guide that adds Prisma ORM to an existing framework project. For a `create-prisma` template project, replace step 1 with the scaffold command and drop the `orm init` step.

````markdown
---
title: '[Your guide title]'
description: '[One sentence: what the reader builds]'
url: /guides/[category]/[slug]
metaTitle: How to use Prisma ORM with [Topic]
metaDescription: '[One sentence for search results]'
---

## Introduction

[What this guide builds and what the reader ends up with. Two or three sentences.]

:::note[Using Prisma ORM 7?]

Prisma ORM 8 is the current release. Prisma ORM 7 remains fully supported; the Prisma ORM 7 version of this guide is at [/guides/v7/[category]/[slug]](/guides/v7/[category]/[slug]).

:::

## Prerequisites

- [Node.js](https://nodejs.org) 24 or later
- A PostgreSQL connection string, or nothing at all: `npx create-db@latest` creates a [Prisma Postgres](/postgres) database for you

## 1. Set up the project

```npm
[Framework scaffold command]
```

## 2. Add Prisma ORM

```npm
npx prisma@latest orm init --target postgres
```

```text no-copy
[Trimmed real output]
```

Set the connection string:

```bash title=".env"
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
```

## 3. Define the contract

```prisma title="src/prisma/contract.prisma"
[Your models]
```

```npm
npx prisma contract emit
```

## 4. Initialize the database

```npm
npx prisma db init
```

```text no-copy
"summary": "Applied N operation(s) across 1 space(s), database signed"
```

## 5. [Integration-specific steps]

[Framework or platform steps, each with its command and real output]

## Common gotchas

[Failures you hit while validating, with the verbatim error and the fix]

## Use with your agent

To delegate this guide to your coding agent, copy the prompt below and hand it over:

<AgentPrompt>

```text
[Numbered instructions an agent can follow to complete this guide, referencing https://www.prisma.io/docs/guides/[category]/[slug].md]
```

</AgentPrompt>

Run [`npx prisma@latest init`](/cli/init) once to install the [Prisma ORM skills](/ai/tools/skills#available-skills-for-prisma-8) for your coding agent. Prompts that map to this guide:

- "[Prompt 1]"
- "[Prompt 2]"

## Next steps

- [Learn the fundamentals](/orm/fundamentals/reading-data): filtering, sorting, pagination, and writes.
- [Read the Prisma ORM overview](/orm) for the concepts behind contracts and typed queries.
````

## Adding guides to navigation [#adding-guides-to-navigation]

Guides are organized by category in subdirectories. To add a guide to the navigation, update the category's `meta.json`:

```json title="apps/docs/content/docs/guides/frameworks/meta.json"
{
  "title": "Frameworks",
  "defaultOpen": true,
  "pages": [
    "nextjs",
    "astro",
    "nuxt",
    "your-new-guide" // [!code ++]
  ]
}
```

The page name is the `.mdx` filename without the extension. The top-level `guides/meta.json` lists the categories, and `guides/v7/meta.json` plus `guides/v7/<category>/meta.json` do the same for the Prisma ORM 7 tree.

## Next steps [#next-steps]

* Read the [Hono](https://www.prisma.io/docs/guides/frameworks/hono) guide and match its shape.
* Validate your guide end to end, then open a pull request with the sandbox commands you ran in the description.

## Related pages

- [`Guides`](https://www.prisma.io/docs/guides/v7): A collection of guides for various tasks and workflows