GraphQL Server with Fastify, Mercurius, Prisma, and Nexus Example
⚠️ Warning!
This repository is no longer maintained and some of the packages may be out of date.
Nonetheless, there are two patterns in here that I think are still really useful for anyone building a GraphQL API:
- Code-first GraphQL schema construction. I still think this is the way to go if you like type safety and TypeScript. I would probably switch Nexus and nexus-prisma for Pothos. You can learn about this Pothos in this talk from the Pothos creator. The main benefit I see of Pothos over Nexus is simplicity and more active development.
- Observability & Tracing: having visibility into the health of your GraphQL API is essential, as I demo in this talk.
Intro
This repo shows how to build a GraphQL server with TypeScript and the following technologies:
- Fastify: Fast and low overhead web framework, for Node.js
- Mercurius: GraphQL adapter for Fastify
- Nexus: Declarative, Code-First GraphQL Schemas for JavaScript/TypeScript
- nexus-prisma: Plugin that allows projecting types from your Prisma schema to the GraphQL schema
- Prisma: Next-generation ORM for type-safe interaction with the database
- PostgreSQL: powerful, open source object-relational database system with over 30 years of active development.
- OpenTelemetry Tracing: An observability framework for cloud-native software. Configured to trace HTTP requests, GraphQL resolution and Prisma queries.
- Altair GraphQL: GraphQL Web Client (similar to GraphQL Playground and Gr)
The project is written in TypeScript and attempts to maintain a high degree of type-safety by leveraging Prisma and GraphQL.
Play with a deployed version of this API: https://fastify-prisma.up.railway.app/altair
🚢
Deploy it!
DB Schema
The database schema is defined using the Prisma schema which defines 3 models:
- User
- Post
- Comment
GraphQL schema
The GraphQL schema is defined with Nexus using the code-first approach.
The relevant files are:
- ./src/schema.ts: Source of truth for the schema in TypeScript
- ./schema.graphql: Generated GraphQL scehma
Getting started
Prerequisites
- A PostgreSQL DB
Steps
- clone repo
- create
.env
file and defineDATABASE_URL
andSENTRY_DSN
npm install
npm run migrate:dev
to run shcema migrations with Prisma Migratenpm run dev
to start dev server and run the API
Tracing
The GraphQL server is instrumented with OpenTelemetry tracing.
Here's how it works:
@autorelic/fastify-opentelemetry
is a plugin that creates a root span for every fastify HTTP request and allows creating child spans usingrequest.openTelemetry()
@opentelemetry/instrumentation-graphql
provides auto-instrumentation for GraphQL execution- Additional spans for Prisma Client queries are created in the GraphQL resolvers through
context.request.openTelemetry()
.
Example trace
Viewing traces in local development with Jaeger
You can view traces in local development using Jaeger.
- Start jaeger by going into the tracing folder and running
docker compose up -d
- In your
.env
file setJAEGER_EXPORTER="true"
- Open the Jaeger UI:
http://localhost:16686/