Skip to main content

How to write guides for Prisma ORM

5 min

Introduction​

This guide shows you how to write guides for Prisma ORM documentation. It covers the required structure, formatting, and style conventions to ensure consistency across all guides. You'll learn about frontmatter requirements, section organization, and writing style.

Prerequisites​

Before writing a guide, make sure you have:

  • A clear understanding of the topic you're writing about
  • Access to the Prisma documentation repository
  • Familiarity with Markdown and MDX
  • Knowledge of the target audience for your guide

Guide structure​

Required frontmatter​

Every guide must include the following frontmatter at the top of the file:

---
title: 'How to [do something] with Prisma ORM'
metaTitle: 'How to [do something] with Prisma ORM'
description: 'Learn how to [do something] with Prisma ORM'
sidebar_label: '[Concise Label]'
image: '/img/guides/[guide-name]-cover.png'
community_section: true
---
  • title: Should be action-oriented and start with "How to"
  • metaTitle: Usually matches the title, used for SEO
  • description: A one-sentence summary starting with "Learn how to", used for SEO
  • sidebar_label: A concise label for the sidebar navigation
  • image: A unique header image for social media sharing (coordinate with the design team)

All frontmatter fields should be in sentence case, except for image.

Required sections​

  1. Introduction

    • Brief overview of what the guide covers
    • What the reader will learn/accomplish
    • Link to any example repositories or related resources

  2. Prerequisites

    • Required software/tools with version numbers
    • Required knowledge/experience
    • Any necessary accounts or access

  3. Main content sections

    • Numbered steps for procedural guides (e.g., "1. Set up the project")
    • Clear hierarchy with H2 (##) for main sections
    • H3 (###) for subsections
    • Each step should build on previous steps

  4. Next steps

    • What to do after completing the guide
    • Related guides or documentation
    • Links to additional resources
    • Community resources (e.g., Discord)

Writing style and voice​

General principles​

  • Write in a clear, conversational tone
  • Use active voice and present tense
  • Address the reader directly using "you"
  • Use first person plural ("we") when guiding the reader through steps
  • Avoid jargon and explain technical terms
  • Be concise but thorough

Code examples​

  • Include complete, runnable code examples
  • Use syntax highlighting with language specification
  • Include file paths in code block metadata
  • Use comments to explain complex parts
  • Show both the problem and solution when applicable

Example:

src/index.ts
// Import required dependencies
import { PrismaClient } from '@prisma/client'

// Initialize Prisma Client
const prisma = new PrismaClient()

Formatting conventions​

  • Use backticks for:
    • File names: `schema.prisma`
    • Directory names: `prisma/`
    • Code elements: `PrismaClient`
    • Commands: `npx prisma generate`
  • Use admonitions for important notes, warnings, tips, etc.: 
    :::note
    Important information goes here
    :::
  • Use proper heading hierarchy (never skip levels)
  • Include line numbers in longer code blocks
  • Use tabbed content for alternative approaches

Examples from existing guides​

Migration guide format​

Migration guides follow a specific pattern, as seen in guides like Migrate from Sequelize and Migrate from Mongoose:

  1. Clear introduction explaining the migration path
  2. Prerequisites specific to both ORMs
  3. Step-by-step migration process
  4. Code comparison between ORMs
  5. Practical examples of common operations

Integration guide format​

Integration guides, like Using Prisma ORM with Cloudflare D1, focus on:

  1. Setup and configuration
  2. Platform-specific considerations
  3. Step-by-step implementation
  4. Deployment instructions
  5. Platform-specific best practices

Best practices​

  1. Keep it focused

    • Each guide should cover one main topic
    • Break complex topics into multiple guides
    • Link to related guides instead of duplicating content

  2. Show don't tell

    • Include practical, real-world examples
    • Provide complete, working code samples
    • Explain why certain approaches are recommended

  3. Consider the context

    • Explain prerequisites clearly
    • Don't assume prior knowledge
    • Link to foundational concepts within or outside of our docs when needed

  4. Maintain consistency

    • Follow the established guide structure
    • Use consistent terminology
    • Match the style of existing guides

  5. Think about maintenance

    • Use version numbers where appropriate
    • Avoid time-sensitive references
    • Consider future updates when structuring content

Template​

This is a template for a guide. It is to standarize the format of the guide, the prisma integration, and make it easier to write a guide.

Before you submit a PR, run through the checklist and make sure to read all Dev Note's and remove them.

To get the guide into the sidebar, you need to add the following to the sidebars.ts file:

sidebars.ts
{
  type: "category",
  label: "Framework Guides",
  collapsed: false,
  collapsible: false,
  items: [
    "guides/turborepo",
    "guides/nextjs",
    "guides/nuxt",
    "guides/tanstack-start",
    "guides/react-router-7",
    "guides/solid-start",
    "guides/sveltekit",
    "guides/__________",
  ].sort(),
},

Copy and paste the template into a new .mdx file:

---
title: 'How to use Prisma ORM with __________'
metaTitle: 'How to use Prisma ORM and Prisma Postgres with __________'
description: 'Learn how to use Prisma ORM in a __________ app'
sidebar_label: '__________ with Prisma'
image: '/img/guides/prisma-__________-cover.png'
completion_time: '15 min'
community_section: true
---

:::warning

DEVELOPER CHECKLIST - Remove upon completion

- [ ] `CTRL or CMD + F` to find 10 `_`'s and replace them with the framework name.

- [ ] Provide a brief overview of the guide's purpose and the benefits of integrating Prisma ORM with the specified framework.

- [ ] Link to the official documentation of the framework upon its first mention in the Introduction section.

- [ ] List all necessary or recommended prerequisites, including specific software versions and any required accounts or services.

- [ ] Name project *<u>framework</u>*-prisma (ie. *<u>sveltekit</u>*-prisma)

- [ ] Project creation options should be detailed in an info admonition in this format:
```markdown
markdown - *Which package manager would you like to use?* `npm` 
```
- [ ] Ensure the appropriate admonitions (note, warning, tip) are used for important information.

- [ ] Include links to related guides and resources throughout the content.

- [ ] Instead of using `we, we'll, ours, etc.` use `you, you'll, yours, etc.`

- [ ] All lines ending before a code block should end with a colon (This one -> `:`)

:::

## Introduction

Prisma ORM streamlines database access with type-safe queries, and when paired with [__________](https://example.com/), it creates a...

:::warning

***DEV NOTE:*** Above, briefly explain the benefits of using Prisma ORM with the specified framework after `it creates a...`

:::

In this guide, you'll learn to integrate Prisma ORM with a Prisma Postgres database in a __________ project from scratch. You can find a complete example of this guide on [GitHub](https://github.com/prisma/prisma-examples/tree/latest/orm/__________).

## Prerequisites
- [Node.js 18+](https://nodejs.org)

## 1. Set up your project

## 2. Install and Configure Prisma

### 2.1. Install dependencies

To get started with Prisma, you'll need to install a few dependencies:

```terminal
npm install prisma --save-dev
npm install tsx --save-dev
npm install @prisma/extension-accelerate
```

:::info
If you're not using a Prisma Postgres database, you can skip `@prisma/extension-accelerate`.
:::

Once installed, initialize Prisma in your project:

:::warning
***DEV NOTE:*** Make sure you update the output path accordingly with the framework (ie. Next.js is `../app/generated/prisma`). and follow through with the proper import paths going forward. This template will be using `../generated/prisma`.
:::

```terminal
npx prisma init --db --output ../generated/prisma
```
:::info
You'll need to answer a few questions while setting up your Prisma Postgres database. Select the region closest to your location and a memorable name for your database like "My __________ Project"
:::
This will create:

- A `prisma/` directory with a `schema.prisma` file
- A `.env` file with a `DATABASE_URL` already set

### 2.2. Define your Prisma Schema

In the `prisma/schema.prisma` file, add the following models:

:::warning

***DEV NOTE:*** If using Vite, the generator client should not include `-js` in the provider:

```prisma file=prisma/schema.prisma
generator client {
	//add-next-line
  provider = "prisma-client"
  //delete-next-line
  provider = "prisma-client-js"
  output   = "../generated/prisma"
}
```

In addition, update the text above this and add "*and change the generator to use the `prisma-client` provider*"

:::

```prisma file=prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
  output   = "../generated/prisma"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

//add-start
model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
  posts Post[]
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
  authorId  Int
  author    User    @relation(fields: [authorId], references: [id])
}
//add-end
```

This creates two models: `User` and `Post`, with a one-to-many relationship between them.

### 2.3. Configure the Prisma Client generator

Now, run the following command to create the database tables and generate the Prisma Client:

```terminal
npx prisma migrate dev --name init
```
### 2.4. Seed the database

Let's add some seed data to populate the database with sample users and posts.

Create a new file called `seed.ts` in the `prisma/` directory:

```typescript file=prisma/seed.ts showLineNumbers
//add-next-line
import { PrismaClient, Prisma } from "../src/generated/prisma";

//add-next-line
const prisma = new PrismaClient();

//add-start
const userData: Prisma.UserCreateInput[] = [
  {
    name: "Alice",
    email: "alice@prisma.io",
    posts: {
      create: [
        {
          title: "Join the Prisma Discord",
          content: "https://pris.ly/discord",
          published: true,
        },
        {
          title: "Prisma on YouTube",
          content: "https://pris.ly/youtube",
        },
      ],
    },
  },
  {
    name: "Bob",
    email: "bob@prisma.io",
    posts: {
      create: [
        {
          title: "Follow Prisma on Twitter",
          content: "https://www.twitter.com/prisma",
          published: true,
        },
      ],
    },
  },
];
//add-end

//add-start
export async function main() {
  for (const u of userData) {
    await prisma.user.create({ data: u });
  }
}
//add-end

//add-next-line
main();
```

Now, tell Prisma how to run this script by updating your `package.json`:

```json file=package.json
//add-start
"prisma": {
  "seed": "tsx prisma/seed.ts"
}
//add-end
```

Run the seed script:

```terminal
npx prisma db seed
```

And open Prisma Studio to inspect your data:

```terminal
npx prisma studio
```



## 3. Integrate Prisma into __________

### 3.1. Create a Prisma Client

Create a `/lib` directory and a `prisma.ts` file inside it. This file will be used to create and export your Prisma Client instance.

Set up the Prisma client like this:

<TabbedContent code>
<TabItem value="Prisma Postgres (recommended)">
```tsx file=src/lib/prisma.ts showLineNumbers
import { PrismaClient } from "../generated/prisma";
import { withAccelerate } from "@prisma/extension-accelerate";

const prisma = new PrismaClient().$extends(withAccelerate());

export default prisma;
```
</TabItem>

<TabItem value="Other databases">
```tsx file=src/lib/prisma.ts showLineNumbers
import { PrismaClient } from "../generated/prisma";

const prisma = new PrismaClient();

export default prisma;
```
</TabItem>
</TabbedContent>

:::warning
We recommend using a connection pooler (like [Prisma Accelerate](https://www.prisma.io/accelerate)) to manage database connections efficiently.

If you choose not to use one, **avoid** instantiating `PrismaClient` globally in long-lived environments. Instead, create and dispose of the client per request to prevent exhausting your database connections.
:::

### 3.2.

:::warning
***DEV NOTE:*** How do you implement prisma into the framework?
:::

You're done! You've just created a __________ app with Prisma ORM. Below are some next steps to explore, as well as some more resources to help you get started expanding your project.

## Next Steps

Now that you have a working __________ app connected to a Prisma Postgres database, you can:

- Extend your Prisma schema with more models and relationships
- Add create/update/delete routes and forms
- Explore authentication and validation
- Enable query caching with [Prisma Postgres](/postgres/caching) for better performance

### More Info

- [Prisma Documentation](/orm/overview/introduction)
- [__________ Documentation](https://example.com/)

Next steps​

After reading this guide, you can:

  • Start writing your own guide using the provided structure
  • Review existing guides for reference
  • Request a unique header image for your guide
  • Submit your guide for review

For more information:


Stay connected with Prisma

Continue your Prisma journey by connecting with our active community. Stay informed, get involved, and collaborate with other developers:

We genuinely value your involvement and look forward to having you as part of our community!