Writing guides

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

• 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

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: a new project scaffolded with create-prisma, deployed to Prisma Compute.
• PostgreSQL, existing project: the orm init and contract infer path for an app that already exists.

Guide structure

Required frontmatter

---
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

1. Introduction (## Introduction): what the guide builds, in two or three sentences, followed by the Using Prisma ORM 7? note (see Versioning).
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. Use with your agent (## Use with your agent): 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.
4. 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.
5. Common gotchas (## Common gotchas): the failures you hit while validating, with the verbatim error text and the fix.
6. Prompt your coding agent (## Prompt your coding agent): a pointer to npx prisma@latest init for the Prisma ORM skills and two or three follow-up prompts that map to the guide.
7. Next steps (## Next steps): links to the fundamentals and the related Prisma ORM pages.

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

• 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

• Backticks for file names (contract.prisma), directories (src/prisma/), commands, and code elements (db.orm.public.User).
• Admonitions for asides:

  :::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

Versions in commands

Guides use floating tags, never pinned versions:

bunx create-prisma@latest my-app --template hono --provider postgres
bunx prisma@latest orm init --target postgres
bunx create-db@latest

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

New project

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

bunx create-prisma@latest my-app --template next --provider postgres

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

Add Prisma ORM to an app that already exists:

bunx prisma@latest orm init --target postgres

For a database that already has tables, follow with npx prisma@latest 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 (set "type": "module"), and contract infer writes Timestamptz for timestamp columns while the runtime on Node.js needs TimestamptzString.

Runtime instantiation

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

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

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

Queries are namespace-qualified (db.orm.public.User.select("id", "email").all()). Close the runtime once on process shutdown with await db.runtime().close(), never per request; in a per-request environment such as Cloudflare Workers, create the client inside the handler instead (see Cloudflare Workers).

Database lifecycle

Environment variables

Show .env files with ```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

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.
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:

:::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/ and add a redirect from the old URL in apps/docs/vercel.json (the file that holds page-level redirects; apps/docs/next.config.mjs only carries the tree-level Prisma ORM 7 cutover rules). Then run pnpm run audit:redirects:strict in apps/docs, which also catches legacy redirects whose destination just moved. Do not leave a Prisma ORM 7 page at a Prisma ORM 8 URL without a version marker.

Guide categories

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.

---
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

## Use with your agent

<AgentPrompt>

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

</AgentPrompt>

## 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@latest contract emit
```

## 4. Initialize the database

```npm
npx prisma@latest 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]

## Prompt your coding agent

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

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

{
  "title": "Frameworks",
  "defaultOpen": true,
  "pages": [
    "nextjs",
    "astro",
    "nuxt",
    "your-new-guide"
  ]
}

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

• Read the 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.