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

1. clone repo
2. create .env file and define DATABASE_URL and SENTRY_DSN
3. npm install
4. npm run migrate:dev to run shcema migrations with Prisma Migrate
5. npm 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 using request.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.

1. Start jaeger by going into the tracing folder and running docker compose up -d
2. In your .env file set JAEGER_EXPORTER="true"
3. Open the Jaeger UI: http://localhost:16686/