brannon-darby/nexus-prisma

Prisma Plugin for Nexus

nexus-prisma

Prisma Plugin for Nexus

Motivation

nexus-prisma generates a working CRUD GraphQL schema based on your prisma datamodel. It leverages nexus code-first power to easily expose/hide/customise types from the generated schema and solve most of the common problems previously faced while using the SDL-first paradigm.

If you want to give it a quick look, check it out here:

Features

• Great DX with built-in (and almost invisible) type-safety
• Easily expose and customise types from your Prisma API
• Automatically resolve queries of Prisma types
• Incrementally adoptable
• Compatible both with TypeScript and JavaScript
• Compatible with any GraphQL Server

Usage

This assumes you are already using prisma.

Install nexus-prisma

yarn add nexus nexus-prisma

Edit your prisma.yml file, and add the following:

hooks:
  post-deploy:
    - prisma generate
      - npx nexus-prisma-generate --client prisma-client-dir --output ./src/generated/nexus-prisma # Runs the codegen tool from nexus-prisma

Then run prisma deploy or npx nexus-prisma-generate. This will generate TS types based on the Prisma GraphQL API.

Once done, you can start using the library as so:

import { GraphQLServer } from 'graphql-yoga'
import { makePrismaSchema, prismaObjectType } from 'nexus-prisma'
import * as path from 'path'
import { prisma } from '__PRISMA_CLIENT_DIR__'
import metaSchema from './generated/nexus-prisma'

const Query = prismaObjectType({ name: 'Query' })
const Mutation = prismaObjectType({ name: 'Mutation' })

const schema = makePrismaSchema({
  // Generated CRUD Query and Mutation types
  types: [Query, Mutation],
  prisma: {
    // Meta schema generated by `nexus-prisma-generate`
    metaSchema,
    // The prisma-client instance
    client: prisma
  },
  outputs: {
    schema: path.join(__dirname, './schema.graphql'),
    typegen: path.join(__dirname, './generated/nexus.ts'),
  },
})

const server = new GraphQLServer({
  schema,
  context: { prisma },
})

server.start(() => console.log(`🚀 Server ready at http://localhost:4000`))

That's it. You can now enjoy a fully working CRUD GraphQL API.

API

prismaObjectType is a wrapper around nexus' objectType. Therefore, everything doable with objectType can also be done with prismaObjectType

import { prismaObjectType } from 'nexus-prisma'

export const Query = prismaObjectType({
  name: 'Query',
  definition(t) {
    t.string('hello')
  },
})

Customizing types from the generated CRUD schema

However, prismaObjectType adds a special method to the t object for you to expose fields of your Prisma GraphQL types.

All the fields exposed using nexus-prisma are automatically resolved. No code is needed besides which fields you want to expose.

Signature (simplified types)

interface Field {
  name: string // Name of the field you want to expose
  alias: string // Name of the alias of you want to give the field
  args: string[] // Arguments of the field you want to expose
}

/**
 * Exposes fields of an object type of the generated CRUD schema
 * Usage: t.prismaFields(['id', { name: 'name', alias: 'firstName' }])
 */
t.prismaFields(fieldsToExpose: string[] | Field[])
/**
 * Exposes fields of an object type of the generated CRUD schema
 * Usage: t.prismaFields({ pick: ['id', { name: 'name', alias: 'firstName' }] })
 * (Equivalent to the above)
 */
t.prismaFields({ pick: string[] | Field[] })
/**
 * Hides fields of an object type of the generated CRUD schema
 * Usage: t.prismaFields({ hide: ['age'] })
 * Usage: t.prismaFields({ hide: (fields) => !fields.includes(['age']) })
 */
t.prismaFields({ filter: (string[] | Field[]) | (fields: string[]) => string[] })

Examples

In its simplest usage, t.prismaFields() expects as input the list of name of fields you want to expose.

import { prismaObjectType } from 'nexus-prisma'

export const Mutation = prismaObjectType({
  name: 'Mutation',
  definition(t) {
    t.prismaFields(['createUser', 'deleteUser']) // Expose 'createUser' and 'deleteUser' mutation from your Prisma GraphQL API
    t.string('hello') // Add other custom fields
  },
})

Alternatively, you can also customise the way you want them exposed using objects:

import { prismaObjectType } from 'nexus-prisma'

export const Query = prismaObjectType({
  name: 'Query',
  definition(t) {
    t.prismaFields(['createUser', { name: 'deleteUser', alias: 'removeUser' }]) // Expose 'createUser' and 'deleteUser' ( as 'removeUser') mutations from your Prisma GraphQL API
    t.int('age') // Expose other custom fields
  },
})

To expose all fields from a type without having to enumerate them, you can also do the following

import { prismaObjectType } from 'nexus-prisma'

export const User = prismaObjectType({ name: 'User' })

// Or the equivalent
export const User = prismaObjectType({
  name: 'User',
  definition(t) {},
})