Prisma Client extensions

From version 4.7.0, you can use Prisma Client extensions to add functionality to your models, result objects, and queries, or to add client-level methods.

You can create an extension with one or more of the following component types:

• model: add custom methods or fields to your models
• client: add client-level methods to Prisma Client
• query: create custom Prisma Client queries
• result: add custom fields to your query results

For example, you might create an extension that uses the model and client component types.

About Prisma Client extensions

When you use a Prisma Client extension, you create an extended client. An extended client is a lightweight variant of the standard Prisma Client that is wrapped by one or more extensions. The standard client is not mutated. You can add as many extended clients as you want to your project. Learn more about extended clients.

You can associate a single extension, or multiple extensions, with an extended client. Learn more about multiple extensions.

You can share your Prisma Client extensions with other Prisma users, and import Prisma Client extensions developed by other users into your Prisma project.

Extensions prerequisites

Prisma Client extensions are available in Preview from version 4.7.0.

To use Prisma Client extensions, you must enable the clientExtensions preview feature flag in the generator block of your schema.prisma file, as follows:

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["clientExtensions"]
}

Create an extension

Use the $extends client-level method to create an extended client. In your $extends structure, use the appropriate extension component or components (model, client, result or query).

For example, the following code uses a model extension component to extend the User model.

const xprisma = prisma.$extends({
  name: `signUp`, // Optional: name appears in error logs
  model: {        // This is a `model` component
    user: { ... } // The extension logic for the `user` model goes inside the curly braces
  },
})

Name an extension for error logs

You can name your extensions to help identify them in error logs. To do so, use the optional field name. For example:

const xprisma = prisma.$extends({
  name: `signUp`,  // (Optional) Extension name
  model: {
    user: { ... }
 },
})

Multiple extensions

You can associate an extension with an extended client in one of two ways:

• You can associate it with an extended client on its own, or
• You can combine the extension with other extensions and associate all of these extensions with an extended client. The functionality from these combined extensions applies to the same extended client. Note: Combined extensions can conflict.

You can combine the two approaches above. For example, you might associate one extension with its own extended client and associate two other extensions with another extended client. Learn more about how client instances interact.

// First of all, store your original Prisma Client in a variable as usual
const prisma = new PrismaClient()

// Declare an extended client that has an extensionA and extensionB
const prismaAB = prisma.$extends(extensionA).$extends(extensionB)

// First of all, store your original Prisma Client in a variable as usual
const prisma = new PrismaClient()

// Declare an extended client that has extensionA applied
const prismaA = prisma.$extends(extensionA)

// Declare an extended client that has extensionB applied
const prismaB = prisma.$extends(extensionB)

// Declare an extended client that is a combination of clientA and clientB
const prismaAB = prismaA.$extends(extensionB)