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

For the complete Prisma documentation index, see 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

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.

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

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.

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

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.

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

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

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

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

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

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.

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

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

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

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.

Add Prisma ORM to an app that already exists:

bunx prisma@latest orm init --target postgres

pnpm dlx prisma@latest orm init --target postgres

yarn dlx prisma@latest orm init --target postgres

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), and contract infer writes Timestamptz for timestamp columns while the runtime on Node.js needs TimestamptzString.

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";
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).

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.

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/, 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.

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

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

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.

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

• Guides: A collection of guides for various tasks and workflows