GraphQL Pattern | Bootspring Docs

Build type-safe GraphQL APIs with Apollo Server, schema definitions, resolvers, DataLoader for N+1 prevention, and client-side integration.

Overview#

GraphQL provides a flexible query language for APIs, allowing clients to request exactly the data they need. This pattern covers setting up a complete GraphQL API with Apollo Server in Next.js.

When to use:

Complex data requirements with nested relationships
Multiple clients needing different data shapes
Real-time features with subscriptions
APIs requiring flexible queries

Key features:

Schema-first development
Type-safe resolvers
DataLoader for N+1 query prevention
Subscriptions for real-time updates
Apollo Client integration

Code Example#

Apollo Server Setup#

// app/api/graphql/route.ts
import { ApolloServer } from '@apollo/server'
import { startServerAndCreateNextHandler } from '@as-integrations/next'
import { typeDefs } from '@/graphql/schema'
import { resolvers } from '@/graphql/resolvers'
import { createContext } from '@/graphql/context'

const server = new ApolloServer({
  typeDefs,
  resolvers
})

const handler = startServerAndCreateNextHandler(server, {
  context: createContext
})

export { handler as GET, handler as POST }

Schema Definition#

// graphql/schema.ts
import { gql } from 'graphql-tag'

export const typeDefs = gql`
  type User {
    id: ID!
    email: String!
    name: String
    posts: [Post!]!
    createdAt: String!
  }

  type Post {
    id: ID!
    title: String!
    content: String
    published: Boolean!
    author: User!
    comments: [Comment!]!
    createdAt: String!
  }

  type Comment {
    id: ID!
    content: String!
    author: User!
    post: Post!
    createdAt: String!
  }

  type Query {
    me: User
    user(id: ID!): User
    users(limit: Int, offset: Int): [User!]!
    post(id: ID!): Post
    posts(published: Boolean, limit: Int, offset: Int): [Post!]!
  }

  type Mutation {
    createUser(input: CreateUserInput!): User!
    updateUser(id: ID!, input: UpdateUserInput!): User!
    deleteUser(id: ID!): Boolean!

    createPost(input: CreatePostInput!): Post!
    updatePost(id: ID!, input: UpdatePostInput!): Post!
    deletePost(id: ID!): Boolean!
    publishPost(id: ID!): Post!

    createComment(input: CreateCommentInput!): Comment!
    deleteComment(id: ID!): Boolean!
  }

  input CreateUserInput {
    email: String!
    name: String
    password: String!
  }

  input UpdateUserInput {
    email: String
    name: String
  }

  input CreatePostInput {
    title: String!
    content: String
    published: Boolean
  }

  input UpdatePostInput {
    title: String
    content: String
    published: Boolean
  }

  input CreateCommentInput {
    postId: ID!
    content: String!
  }
`

Resolvers#

// graphql/resolvers.ts
import { prisma } from '@/lib/db'
import { GraphQLError } from 'graphql'
import { Context } from './context'

export const resolvers = {
  Query: {
    me: async (_: unknown, __: unknown, ctx: Context) => {
      if (!ctx.user) return null
      return prisma.user.findUnique({ where: { id: ctx.user.id } })
    },

    user: async (_: unknown, { id }: { id: string }) => {
      return prisma.user.findUnique({ where: { id } })
    },

    users: async (_: unknown, { limit = 20, offset = 0 }: { limit?: number; offset?: number }) => {
      return prisma.user.findMany({ take: limit, skip: offset })
    },

    post: async (_: unknown, { id }: { id: string }) => {
      return prisma.post.findUnique({ where: { id } })
    },

    posts: async (_: unknown, args: { published?: boolean; limit?: number; offset?: number }) => {
      return prisma.post.findMany({
        where: args.published !== undefined ? { published: args.published } : undefined,
        take: args.limit ?? 20,
        skip: args.offset ?? 0,
        orderBy: { createdAt: 'desc' }
      })
    }
  },

  Mutation: {
    createPost: async (
      _: unknown,
      { input }: { input: { title: string; content?: string; published?: boolean } },
      ctx: Context
    ) => {
      if (!ctx.user) {
        throw new GraphQLError('Not authenticated', {
          extensions: { code: 'UNAUTHENTICATED' }
        })
      }

      return prisma.post.create({
        data: {
          ...input,
          authorId: ctx.user.id
        }
      })
    },

    updatePost: async (
      _: unknown,
      { id, input }: { id: string; input: Partial<{ title: string; content: string; published: boolean }> },
      ctx: Context
    ) => {
      const post = await prisma.post.findUnique({ where: { id } })

      if (!post) {
        throw new GraphQLError('Post not found', {
          extensions: { code: 'NOT_FOUND' }
        })
      }

      if (post.authorId !== ctx.user?.id) {
        throw new GraphQLError('Not authorized', {
          extensions: { code: 'FORBIDDEN' }
        })
      }

      return prisma.post.update({
        where: { id },
        data: input
      })
    },

    deletePost: async (_: unknown, { id }: { id: string }, ctx: Context) => {
      const post = await prisma.post.findUnique({ where: { id } })

      if (!post || post.authorId !== ctx.user?.id) {
        throw new GraphQLError('Not authorized', {
          extensions: { code: 'FORBIDDEN' }
        })
      }

      await prisma.post.delete({ where: { id } })
      return true
    }
  },

  // Field resolvers for relations
  User: {
    posts: (parent: { id: string }) => {
      return prisma.post.findMany({ where: { authorId: parent.id } })
    }
  },

  Post: {
    author: (parent: { authorId: string }) => {
      return prisma.user.findUnique({ where: { id: parent.authorId } })
    },
    comments: (parent: { id: string }) => {
      return prisma.comment.findMany({ where: { postId: parent.id } })
    }
  },

  Comment: {
    author: (parent: { userId: string }) => {
      return prisma.user.findUnique({ where: { id: parent.userId } })
    },
    post: (parent: { postId: string }) => {
      return prisma.post.findUnique({ where: { id: parent.postId } })
    }
  }
}

Context#

// graphql/context.ts
import { NextRequest } from 'next/server'
import { auth } from '@/auth'

export interface Context {
  user: { id: string; email: string } | null
}

export async function createContext({ req }: { req: NextRequest }): Promise<Context> {
  const session = await auth()

  return {
    user: session?.user ? {
      id: session.user.id!,
      email: session.user.email!
    } : null
  }
}

DataLoader for N+1 Prevention#

// graphql/loaders.ts
import DataLoader from 'dataloader'
import { prisma } from '@/lib/db'
import { User, Post } from '@prisma/client'

export function createLoaders() {
  return {
    userLoader: new DataLoader<string, User | null>(async (ids) => {
      const users = await prisma.user.findMany({
        where: { id: { in: [...ids] } }
      })

      const userMap = new Map(users.map(u => [u.id, u]))
      return ids.map(id => userMap.get(id) ?? null)
    }),

    userPostsLoader: new DataLoader<string, Post[]>(async (userIds) => {
      const posts = await prisma.post.findMany({
        where: { authorId: { in: [...userIds] } }
      })

      const postsByUser = new Map<string, Post[]>()
      posts.forEach(post => {
        const existing = postsByUser.get(post.authorId) ?? []
        postsByUser.set(post.authorId, [...existing, post])
      })

      return userIds.map(id => postsByUser.get(id) ?? [])
    })
  }
}

// Updated context
export interface Context {
  user: { id: string; email: string } | null
  loaders: ReturnType<typeof createLoaders>
}

// Updated resolvers using loaders
export const resolvers = {
  Post: {
    author: (parent: { authorId: string }, _: unknown, ctx: Context) => {
      return ctx.loaders.userLoader.load(parent.authorId)
    }
  },
  User: {
    posts: (parent: { id: string }, _: unknown, ctx: Context) => {
      return ctx.loaders.userPostsLoader.load(parent.id)
    }
  }
}

Client-Side Usage#

// lib/graphql/client.ts
import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client'
import { setContext } from '@apollo/client/link/context'

const httpLink = createHttpLink({
  uri: '/api/graphql'
})

const authLink = setContext((_, { headers }) => {
  const token = typeof window !== 'undefined'
    ? localStorage.getItem('token')
    : null

  return {
    headers: {
      ...headers,
      authorization: token ? `Bearer ${token}` : ''
    }
  }
})

export const apolloClient = new ApolloClient({
  link: authLink.concat(httpLink),
  cache: new InMemoryCache()
})

// hooks/usePosts.ts
import { gql, useQuery, useMutation } from '@apollo/client'

const GET_POSTS = gql`
  query GetPosts($limit: Int, $offset: Int) {
    posts(limit: $limit, offset: $offset) {
      id
      title
      content
      published
      author {
        id
        name
      }
    }
  }
`

const CREATE_POST = gql`
  mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
      id
      title
    }
  }
`

export function usePosts(limit = 10) {
  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
    variables: { limit, offset: 0 }
  })

  const loadMore = () => {
    fetchMore({
      variables: { offset: data?.posts.length ?? 0 }
    })
  }

  return { posts: data?.posts ?? [], loading, error, loadMore }
}

export function useCreatePost() {
  const [createPost, { loading, error }] = useMutation(CREATE_POST, {
    refetchQueries: [{ query: GET_POSTS }]
  })

  return { createPost, loading, error }
}

Subscriptions with WebSocket#

// graphql/schema.ts (add subscription type)
const typeDefs = gql`
  type Subscription {
    postCreated: Post!
    commentAdded(postId: ID!): Comment!
  }
`

// graphql/resolvers.ts
import { PubSub } from 'graphql-subscriptions'

const pubsub = new PubSub()

export const resolvers = {
  Mutation: {
    createPost: async (_: unknown, { input }: any, ctx: Context) => {
      const post = await prisma.post.create({
        data: { ...input, authorId: ctx.user!.id }
      })

      pubsub.publish('POST_CREATED', { postCreated: post })

      return post
    }
  },

  Subscription: {
    postCreated: {
      subscribe: () => pubsub.asyncIterableIterator(['POST_CREATED'])
    },
    commentAdded: {
      subscribe: (_: unknown, { postId }: { postId: string }) => {
        return pubsub.asyncIterableIterator([`COMMENT_ADDED_${postId}`])
      }
    }
  }
}

Usage Instructions#

Set up Apollo Server: Create the GraphQL endpoint with Next.js integration
Define schema: Write your GraphQL type definitions
Implement resolvers: Create resolver functions for queries and mutations
Add context: Set up authentication and loaders in context
Implement DataLoaders: Prevent N+1 queries with batching
Create client: Set up Apollo Client for frontend consumption

Best Practices#

Use DataLoader - Always batch related queries to prevent N+1 problems
Validate in resolvers - Check authentication and authorization
Use GraphQL errors - Throw GraphQLError with appropriate codes
Keep resolvers thin - Move business logic to services
Schema-first development - Define schema before implementing resolvers
Use fragments - Share field selections across queries
Monitor performance - Track resolver execution times

Route Handler - REST API alternative
Error Handling - Error response patterns
React Query - Alternative to Apollo Client
WebSockets - Real-time communication