Skip to main content

Comprehensive Guide to Using Prisma ORM with Next.js

Prisma ORM and Next.js form a powerful combination for building modern, server-side rendered, and API-driven web applications. This guide consolidates various tips and strategies to help you maximize their potential. Whether you’re looking for best practices, monorepo setup guidance, or strategies for dynamic usage, we’ve got you covered.

Best practices for using Prisma Client in development​

Avoid multiple Prisma Client instances​

When developing a Next.js application, one common issue is accidentally creating multiple instances of the Prisma Client. This often occurs due to Next.js’s hot-reloading feature in development.

Why this happens​

Next.js’s hot-reloading feature reloads modules frequently to reflect code changes instantly. However, this can lead to multiple instances of Prisma Client being created, which consumes resources and might cause unexpected behavior.

To avoid this, create a single Prisma Client instance by using a global variable:

// lib/prisma.ts
import { PrismaClient } from "@prisma/client";

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma =
  globalForPrisma.prisma || new PrismaClient();

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

Using this approach ensures that only one instance of Prisma Client exists, even during hot-reloading in development.

Setting Up Prisma ORM in a Monorepo​

Challenges of using Prisma ORM in monorepos​

Monorepos allow multiple projects to share code and dependencies, making them a popular choice for modern development. However, using Prisma ORM in a monorepo can present challenges related to dependency resolution and schema management.

Key issues​

  1. Dependency Resolution: Multiple packages in a monorepo might lead to conflicts if they use different version of Prisma ORM.
  2. Schema Centralization: Managing a single Prisma Schema across multiple projects can be complex.

Best practices for monorepo integration​

  • Centralize the Prisma Schema: Place the schema.prisma file in a shared package, such as @myorg/db, to ensure consistency.
  • Install Dependencies in the Root: Avoid version conflicts by installing Prisma ORM as a dependency at the root of the monorepo.
  • Use NPM Scripts for Generation:
{
  "scripts": {
    "prisma:generate": "prisma generate --schema=./packages/db/schema.prisma"
  }
}

This approach keeps your Prisma Schema and generated client in sync across all projects in the monorepo.

Dynamic usage of Prisma Client in Next.js​

Handling dynamic scenarios​

Dynamic use cases, such as working with tenant-specific databases, require additional consideration when using Prisma ORM with Next.js.

Problem​

Each tenant might have its own database, necessitating the creation of separate Prisma Clients at runtime. This can be complex in Next.js due to its hybrid rendering model.

Solution​

Use a factory function to dynamically create Prisma Clients based on tenant-specific configurations:

// lib/prismaDynamic.ts
import { PrismaClient } from "@prisma/client";

type TenantConfig = {
  databaseUrl: string;
};

export function createPrismaClient(config: TenantConfig): PrismaClient {
  return new PrismaClient({
    datasources: {
      db: {
        url: config.databaseUrl,
      },
    },
  });
}

Ensure that you manage the lifecycle of dynamically created Prisma Clients to avoid resource exhaustion.