GraphQL Server Boilerplate with Apollo Server, Prisma2, and nexus/schema

My team, dooboolab, and I were building GraphQL Server with Apollo-Server, Prisma2, and nexus/schema. As both Prisma2 and nexus/shema are released in 2019, the information about Apollo-server with Prisma2 and nexus/schema is not easy to find even through Googling. That’s why we want to share our experience that we’ve learned from using it in building our backend server. You can check why we chose Prisma2 & nexus/schema here.

Recommend to have a bit of knowledge about libraries and tools below.

Prerequisites

• yarn
• TypeScript (Nexus currently only works with TypeScript)
• PostgreSQL

Let’s find out how to set up with Prisma2 and nexus/schema from scratch in four separate steps.

Step 1 : Setting up Typescript & Postgress

First, Typescript should be set up as nexus requires it mandatorily.

Typescript

$ yarn add --dev ts-node-dev typescript
$ touch tsconfig.json

If you don’t have your own tsconfig.json, you can use this.

{
  "baseUrl": "types",
  "typeRoots": ["types"],
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "module": "commonjs",
    "moduleResolution": "node",
    "target": "es2017",
    "esModuleInterop": true,
    "allowJs": true,
    "allowSyntheticDefaultImports": true,
    "declaration":false,
    "noLib":false,
    "sourceMap":true,
    "pretty":true,
    "allowUnreachableCode":true,
    "allowUnusedLabels":true,
    "noImplicitAny":false,
    "noImplicitReturns":false,
    "noImplicitUseStrict":false,
    "outDir":"dist/",
    "baseUrl":"src/",
    "listFiles":false,
    "skipLibCheck": true
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "tests/**/*"
  ]
}

We should set up a database(RDBMs) too. Of course, you can choose another database. But the reason we picked PostgreSQL as a database is that both Prisma and Nexus recommend it over other databases. You can read why Prisma chose PostgreSQL as its preferred database here and also here for the reason of Nexus.

Install and run PostgreSQL on MacOS

$ brew install postgresql
$ brew services start postgresql
$ createuser -P -s <userId>
$ psql postgres
postgres=# CREATE DATABASE <databaseName>;

If you need more information for setting up PostgreSQL, visit the below pages.

https://flaviocopes.com/postgres-how-to-install/

https://www.codementor.io/@engineerapart/getting-started-with-postgresql-on-mac-osx-are8jcopb

Step 2 : Apollo-Server

It’s time to set up a GraphQL Server. We will use Apollo-Server as our GraphQL Server. Create a package.json file and install Apollo-Server library.

$ yarn init --yes
$ yarn add apollo-server

After installing Apollo-Server, create and run Apollo-Sever as below. But the server won’t work with the below code. You need to define your own typeDefs, resolvers. We will cover this too in the section of step 4.

src/server.ts

To start a server with yarn command, add dev command to scripts of package.json.

package.json

Step 3: nexus/schema

The next step is installing nexus/schema and other dependent packages.

$ yarn add @nexus/schema nexus nexus-plugin-prisma

nexus-plugin-prisma is the library that connects Prisma and Nexus. We will install other prima libraries in step 4 too.

We need to define src/schema.ts file which contains ‘makeSchema’ function. In nexus/schema, types are implemented by makeSchema function. We can set output paths by passing the ‘outputs’ argument to make both GraphQL schema & types.

src/schema.ts

schema that this module returns is passed to ApolloServer in src/server.ts as below.

Add a command generate:nexus run the file src/schema.ts.

package.json

Before executing this command, we have to define model types with Prisma2 and other Prisma related settings. We will do this in the next step.

Step 4: Prisma2

To use Prisma2, we need these two libraries.

@prisma/client
@primsa/cli

But, the libraries we need are already installed when we installed nexus-plugin-prisma, so no need to install them again. You would get an error message if you install them.
And add commands for Prisma2 as well.

package.json

The role of the commandgenerate:prisma or prisma generate is creating node_modules/@prisma/client directory. You might wonder why node_modules/@prisma/client already exists in your local code even before you execute that command. This is because prisma generate is executed immediately after you install @prisma/client. But you need to run this command whenever there is a change in Prisma schema. You can read more explanation here.

The commandprisma generate is all about Prisma Client, not Prisma Migrate. Therefore, we need to create database tables by running migrate:save and migrate:up which are the commands of Prisma Migrate.

Before creating database tables with these two commands, we need to configure models.ts and prisma directory. You can define your own model.

models.ts

As you can see, each model is defined using nexus/schema’s objectType. For more information, check nexus/schema docs here.

Step 5: Prisma Migrate

Then, run npx prisma init to create a default directory called prisma which contains config files .env and schema.prisma.
You need to fill those files for your own service.

.env file

DATABASE_URL="postgresql://<userName>:<password>@localhost:5432/<databaseName>

schema.prisma

As we have completed Primsa2 conifg, we can run save migrate command.

$ yarn migrate:save --name init

Then you could find a newly created migration folder like ‘20200618190347-init’.

After that, run up command again to actually reflect the migration script to the database.

$ yarn migrate:up

Connect to the database to check whether the tables are created successfully.

$ psql <databaseName>
postgres=# \dt

If you create a database as a schema, use this:

$ psql <databaseName>
postgres=# \dt <schemaName>.

Step 6: Generate schema & type file of GraphQL

Now that we finish all Prisma configuration, we should run yarn generate:nexus command that I mentioned in step 3.

This will create GraphQL type file src/generated/nexus.ts and also GraphQL schema file schema.graphql.

src/generated/nexus.ts

schema.graphql

schema.graphql is GraphQL SDL (Schema Definition Language). And src/generated/nexus.ts is the most important core file that actually runs GraphQL Server.

Step 7: Test the server

Now, as we are all ready, let’s run the command to start GraphQL Server.

$ yarn dev
or
$ npm run dev

If the server works properly, try Queries or Mutations too.

signUp Mutation

me Query

It’s all done!

Thanks for following the all steps.

If you have some trouble following this tutorial you can check all code in the github repository. Or you can leave a comment freely.

Reference

Get started with Apollo Server

apollo-server-express

Prisma Documentation (Concepts, Reference & Guides)

Nexus

Nexus Prisma · GraphQL Nexus