Features

💡

The following use abbreviated examples that skip a complete setup of passing Nexus type definition to Nexus' makeSchema. If you are new to Nexus, consider reading the official Nexus tutorial (opens in a new tab) before jumping into Nexus Prisma.

Type-safe Generated Library Code

Following the same philosophy as Prisma Client, Nexus Prisma uses generation to create an API that feels tailor made for your project.

model User {
  id  String  @id
}

import { User } from 'nexus-prisma'
import { objectType } from 'nexus'
 
objectType({
  name: User.$name
  description: User.$description
  definition(t) {
    t.field({
      type: User.id.type,
      description: User.id.description
    })
  }
})

Project Enums

Every enum defined in your Prisma schema becomes importable as a Nexus enum type definition configuration. This makes it trivial to project enums from your database layer into your API layer.

enum SomeEnum {
  foo
  bar
}

import { SomeEnum } from 'nexus-prisma'
import { enumType } from 'nexus'
 
SomeEnum.name //    'SomeEnum'
SomeEnum.members // ['foo', 'bar']
 
enumType(SomeEnum)

Project Scalars

Like GraphQL, Prisma has the concept of scalar types (opens in a new tab). Some of the Prisma scalars can be naturally mapped to standard GraphQL scalars. The mapping is as follows:

Prisma Standard Scalar to GraphQL Standard Scalar Mapping

Prisma	GraphQL
`Boolean`	`Boolean`
`String`	`String`
`Int`	`Int`
`Float`	`Float`
`String` with `@id`	`ID`
`Int` with `@id`	`ID` \| `Int` (configurable)

However some of the Prisma scalars do not have a natural standard representation in GraphQL. For these cases Nexus Prisma generates code that references type names matching those scalar names in Prisma. Then, you are expected to define those custom scalar types in your GraphQL API. Nexus Prisma ships with pre-defined mappings in nexus-prisma/scalars you can use for convenience. The mapping is as follows:

Prisma Standard-Scalar to GraphQL Custom-Scalar Mapping

Prisma	GraphQL	Nexus `t` Helper	GraphQL Scalar Implementation	Additional Info
`Json`	`Json`	`json`	JsonObject (opens in a new tab)
`DateTime`	`DateTime`	`dateTime`	DateTime (opens in a new tab)
`BigInt`	`BigInt`	`bigInt`	BigInt (opens in a new tab)	JavaScript BigInt (opens in a new tab)
`Bytes`	`Bytes`	`bytes`	Byte (opens in a new tab)	Node.js Buffer (opens in a new tab)
`Decimal`	`Decimal`	`decimal`	(internal)	Uses Decimal.js (opens in a new tab)

💡

Not all Prisma scalar mappings are implemented yet: Unsupported

💡

BigInt is supported in Node.js since version 10.4.0 (opens in a new tab) however to support BigInt in JSON.parse/JSON.stringify you must use json-bigint-patch (opens in a new tab) otherwise BigInt values will be serialized as strings.

You can use your own GraphQL Scalar Implementation, however, you must adhere to the above Prisma/GraphQL name mapping defined above.

Here is an example using Nexus Prisma's pre-defined GraphQL custom scalars:

import NexusPrismaScalars from 'nexus-prisma/scalars'
import { makeSchema } from 'nexus'
 
makeSchema({
  types: [NexusPrismaScalars],
})

There is a recipe below showing how to add your own custom scalars if you want.

Project Relations

You can project relations (opens in a new tab) into your API with Nexus Prisma. Nexus Prisma even includes the resolver you'll need at runtime to fulfill the projection by automating use of your Prisma Client instance.

Please note that not all kinds of relationships are supported yet. Details about projecting each kind of relation are documented in their respective sections. This section only contains general documentation common to all.

To project relations you must by default expose an instance of Prisma Client on the GraphQL context under the key name prisma. You can customize which context property Nexus Prisma should look for your Prisma Client.

Example: Exposing Prisma Client on GraphQL Context with Apollo Server

import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import { PrismaClient } from '@prisma/client'
import schema from './your/schema/somewhere'
 
const prisma = new PrismaClient()
 
const apolloServer = new ApolloServer({
  schema,
})
 
startStandaloneServer(apolloServer, {
  context: async () => {
    return {
      prisma,
    }
  },
}).then(({ url }) => {
  console.log('GraphQL API ready at', url)
})

Project 1:1 Relation

You can project 1:1 relationships (opens in a new tab) into your API.

Example: Tests

The integration test suite is a useful reference as it is declarative (easy to read) and gives a known-working example spanning from database all the way to executed GraphQL document.

Example: Full 1:1

// Database Schema
 
model User {
  id         String  @id
  profile    Profile @relation(fields: [profileId], references: [id])
  profileId  String
}
 
model Profile {
  id      String  @id
  user    User?
}

// API Schema
 
import { User, Profile } from 'nexus-prisma'
 
queryType({
  definition(t) {
    t.nonNull.list.nonNull.field('users', {
      type: 'User',
      resolve(_, __, ctx) {
        return ctx.prisma.user.findMany()
      },
    })
  },
})
 
objectType({
  name: User.$name,
  definition(t) {
    t.field(User.id)
    t.field(User.profile)
  },
})
 
objectType({
  name: Profile.$name,
  definition(t) {
    t.field(Profile.id)
  },
})

# API Schema Represented in GraphQL SDL (this is generated by Nexus)
 
type Query {
  users: [User!]!
}
 
type User {
  id: ID
  profile: Profile
}
 
type Profile {
  id: ID
}

// Example Database Data (for following example)
 
await prisma.user.create({
  data: {
    id: 'user1',
    profile: {
      create: {
        id: 'profile1',
      },
    },
  },
})

# Example API Client Query
 
query {
  users {
    id
    profile {
      id
    }
  }
}

{
  "data": {
    "users": [
      {
        "id": "user1",
        "profile": {
          "id": "profile1"
        }
      }
    ]
  }
}

Limitation: Nullable on Without-Relation-Scalar Side

Prisma requires that a 1:1 relationship has one side that is optional. For example in the following it is not possible for Profile to have a required relationship to User. For more detail you can read the Prisma docs about this here (opens in a new tab).

model User {
  id         String  @id
  profile    Profile @relation(fields: [profileId], references: [id])
  profileId  String
}
 
model Profile {
  id      String  @id
  user    User?  // <--  "?" required
}

Prisma inherits this limitation from databases. In turn Nexus Prisma inherits this limitation from Prisma. For example consider this projection and then look at the resulting GraphQL SDL representation.

import { User, Profile } from 'nexus-prisma'
 
objectType({
  name: User.$name,
  definition(t) {
    t.field(User.id)
    t.field(User.profile)
  },
})
 
objectType({
  name: Profile.$name,
  definition(t) {
    t.field(Profile.id)
    t.field(User.profile)
  },
})

type User {
  id: ID
  profile: Profile!
}
 
type Profile {
  id: ID
  user: User # <-- Nullable!
}

This limitation may be a problem for your API. There is an issue track this that you can subscribe to (opens in a new tab) if interested. As a workaround for now you can do this:

objectType({
  name: Profile.$name,
  definition(t) {
    t.field(Profile.id)
    t.field({
      ...User.profile,
      type: nonNull(User.profile.type),
    })
  },
})

Project 1:n Relation

You can project 1:n relationships (opens in a new tab) into your API.

Example: Tests

The integration test suite is a useful reference as it is declarative (easy to read) and gives a known-working example spanning from database all the way to executed GraphQL document.

Example: Full 1:n

// Database Schema
 
model User {
  id         String    @id
  posts      Post[]
}
 
model Post {
  id        String  @id
  author    User?   @relation(fields: [authorId], references: [id])
  authorId  String
}

// API Schema
 
import { User, Post } from 'nexus-prisma'
 
queryType({
  definition(t) {
    t.nonNull.list.nonNull.field('users', {
      type: 'User',
      resolve(_, __, ctx) {
        return ctx.prisma.user.findMany()
      },
    })
  },
})
 
objectType({
  name: User.$name,
  definition(t) {
    t.field(User.id)
    t.field(User.posts)
  },
})
 
objectType({
  name: Post.$name,
  definition(t) {
    t.field(Post.id)
  },
})

# API Schema Represented in GraphQL SDL (this is generated by Nexus)
 
type Query {
  users: [User]
}
 
type User {
  id: ID!
  posts: [Post!]!
}
 
type Post {
  id: ID!
}

// Example Database Data (for following example)
 
await prisma.user.create({
  data: {
    id: 'user1',
    posts: {
      create: [{ id: 'post1' }, { id: 'post2' }],
    },
  },
})

# Example API Client Query
 
query {
  users {
    id
    posts {
      id
    }
  }
}

{
  "data": {
    "users": [
      {
        "id": "user1",
        "posts": [
          {
            "id": "post1"
          },
          {
            "id": "post2"
          }
        ]
      }
    ]
  }
}

Projecting Nullability

Currently nullability projection is not configurable. This section describes how Nexus Prisma handles it.

                      Nexus Prisma Projects
                                │
                                │
DB Layer (Prisma)           → → ┴ → →           API Layer (GraphQL)
–––––––––––––––––                               –––––––––––––––––––

Nullable Field Relation                         Nullable Field Relation

model A {                                       type A {
  foo Foo?                                        foo: Foo
}                                               }



Non-Nullable Field Relation                     Non-Nullable Field Relation

model A {                                       type A {
  foo Foo                                         foo: Foo!
}                                               }



List Field Relation                             Non-Nullable Field Relation Within Non-Nullable List

model A {                                       type A {
  foos Foo[]                                      foo: [Foo!]!
}                                               }

If a findOne or findUnique for a non-nullable Prisma field return null for some reason (e.g. data corruption in the database) then the standard GraphQL null propagation (opens in a new tab) will kick in.

Prisma Schema Docs Propagation

As GraphQL schema doc

/// A user.
model User {
  /// A stable identifier to find users by.
  id  String  @id
}

import { User } from 'nexus-prisma'
import { objectType } from 'nexus'
 
User.$description // JSDoc: A user.
User.id.description // JSDoc: A stable identifier to find users by.
 
objectType({
  name: User.$name
  description: User.$description
  definition(t) {
    t.field(User.id)
  }
})

"""
A user.
"""
type User {
  """
  A stable identifier to find users by.
  """
  id: ID
}

As JSDoc

Can be disabled in gentime settings (opens in a new tab).

/// A user.
model User {
  /// A stable identifier to find users by.
  id  String  @id
}

import { User } from 'nexus-prisma'
 
User // JSDoc: A user.
User.id // JSDoc: A stable identifier to find users by.

Rich Formatting

It is possible to write multiline documentation in your Prisma Schema file. It is also possible to write markdown or whatever else you want.

/// # Foo   _bar_
/// qux
///
/// tot
model Foo {
  /// Foo   bar
  /// qux
  ///
  /// tot
  foo  String
}

However, you should understand the formatting logic Nexus Prisma uses as it may limit what you want to achieve. The current logic is:

Strip newlines
Collapse multi-spaces spaces into single-space

So the above would get extracted by Nexus Prisma as if it was written like this:

/// # Foo _bar_ qux tot
model Foo {
  /// Foo bar qux tot
  foo  String
}

This formatting logic is conservative. We are open to making it less so, in order to support more expressivity. Please open an issue (opens in a new tab) if you have an idea.

ESM Support

We are not supporting esm build yet, more info here (opens in a new tab).

Refined DX

These are finer points that aren't perhaps worth a top-level point but none the less add up toward a thoughtful developer experience.

JSDoc

Generated Nexus configuration for fields and models that you have not documented in your PSL get default JSDoc that teaches you how to do so.
JSDoc for Enums have their members embedded

Default Runtime

When your project is in a state where the generated Nexus Prisma part is missing (new repo clone, reinstalled deps, etc.) Nexus Prisma gives you a default runtime export named PleaseRunPrismaGenerate and will error with a clear message.

Peer-Dependency Validation

When nexus-prisma is imported it will validate that your project has peer dependencies setup correctly.

If a peer dependency is not installed it nexus-prisma will log an error and then exit 1. If its version does not satify the range supported by the current version of nexus-prisma that you have installed, then a warning will be logged. If you want to opt-out of this validation (e.g. you're using a bundler) then set an envar as follows:

NO_PEER_DEPENDENCY_CHECK=true|1
PEER_DEPENDENCY_CHECK=false|0

Auto-Import Optimized

nexus-prisma/scalars offers a default export you can easily auto-import by name: NexusPrismaScalars.

Usage Gentime