Extensions

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.

Add an extension to Prisma Client

You can create an extension using two primary ways:

• Use the client-level $extends method

  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
    },
  })

• Use the Prisma.defineExtension method to define an extension and assign it to a variable, and then pass the extension to the client-level $extends method

  import { Prisma } from '@prisma/client'
  
  // Define the extension
  const myExtension = Prisma.defineExtension({
    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
    },
  })
  
  // Pass the extension to a Prisma Client instance
  const xprisma = prisma.$extends(myExtension)

  This pattern is useful for when you would like to separate extensions into multiple files or directories within a project.

The above examples use the model extension component to extend the User model.

In your $extends method, use the appropriate extension component or components (model, client, result or query).

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 prisma = new PrismaClient().$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)

Type of an extended client

You can infer the type of an extended Prisma Client instance using the typeof utility as follows:

const extendedPrismaClient = new PrismaClient().$extends({
  /** extension */
})

type ExtendedPrismaClient = typeof extendedPrismaClient

If you're using Prisma Client as a singleton, you can get the type of the extended Prisma Client instance using the typeof and ReturnType utilities as follows:

function getExtendedClient() {
  return new PrismaClient().$extends({
    /* extension */
  })
}

type ExtendedPrismaClient = ReturnType<typeof getExtendedClient>

Limitations

const prisma = new PrismaClient()

prisma.$use(async (params, next) => {
  console.log('This is middleware!')
  return next(params)
})

const xPrisma = prisma.$extends({
  name: 'myExtension',
  model: {
    user: {
      async signUp(email: string) {
        await prisma.user.create({ data: { email } })
      },
    },
  },
})

const xPrisma = prisma.$extends(...);

if (xPrisma.$connect) {
  xPrisma.$connect()
}