Apollo Server 4.x Guide
Apollo Server is an open-source GraphQL server that works with any GraphQL schema. Version 4.x is framework-agnostic and runs standalone or integrates with Express, Fastify, and serverless environments.
Quick Start Step 1: Install npm install @apollo/server graphql
For Express integration:
npm install @apollo/server express graphql cors
Step 2: Define Schema const typeDefs = `#graphql type Book { title: String author: String }
type Query { books: [Book] } `;
Step 3: Write Resolvers const resolvers = { Query: { books: () => [ { title: 'The Great Gatsby', author: 'F. Scott Fitzgerald' }, { title: '1984', author: 'George Orwell' }, ], }, };
Step 4: Start Server
Standalone (Recommended for getting started):
import { ApolloServer } from '@apollo/server'; import { startStandaloneServer } from '@apollo/server/standalone';
const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, { listen: { port: 4000 }, });
console.log(Server ready at ${url});
Express v4:
import { ApolloServer } from '@apollo/server'; import { expressMiddleware } from '@apollo/server/express4'; import { ApolloServerPluginDrainHttpServer } from '@apollo/server/plugin/drainHttpServer'; import express from 'express'; import http from 'http'; import cors from 'cors';
const app = express(); const httpServer = http.createServer(app);
const server = new ApolloServer({ typeDefs, resolvers, plugins: [ApolloServerPluginDrainHttpServer({ httpServer })], });
await server.start();
app.use( '/graphql', cors(), express.json(), expressMiddleware(server, { context: async ({ req }) => ({ token: req.headers.authorization }), }), );
await new Promise
Schema Definition Scalar Types Int - 32-bit integer Float - Double-precision floating-point String - UTF-8 string Boolean - true/false ID - Unique identifier (serialized as String) Type Definitions type User { id: ID! name: String! email: String posts: [Post!]! }
type Post { id: ID! title: String! content: String author: User! }
input CreatePostInput { title: String! content: String }
type Query { user(id: ID!): User users: [User!]! }
type Mutation { createPost(input: CreatePostInput!): Post! }
Enums and Interfaces enum Status { DRAFT PUBLISHED ARCHIVED }
interface Node { id: ID! }
type Article implements Node { id: ID! title: String! }
Resolvers Overview
Resolvers follow the signature: (parent, args, contextValue, info)
parent: Result from parent resolver (root resolvers receive undefined) args: Arguments passed to the field contextValue: Shared context object (auth, dataSources, etc.) info: Field-specific info and schema details (rarely used) const resolvers = { Query: { user: async (, { id }, { dataSources }) => { return dataSources.usersAPI.getUser(id); }, }, User: { posts: async (parent, , { dataSources }) => { return dataSources.postsAPI.getPostsByAuthor(parent.id); }, }, Mutation: { createPost: async (_, { input }, { dataSources, user }) => { if (!user) throw new GraphQLError('Not authenticated'); return dataSources.postsAPI.create({ ...input, authorId: user.id }); }, }, };
Context Setup
Context is created per-request and passed to all resolvers.
interface MyContext { token?: string; user?: User; dataSources: { usersAPI: UsersDataSource; postsAPI: PostsDataSource; }; }
const server = new ApolloServer
// Standalone const { url } = await startStandaloneServer(server, { context: async ({ req }) => { const token = req.headers.authorization || ''; const user = await getUser(token); return { token, user, dataSources: { usersAPI: new UsersDataSource(), postsAPI: new PostsDataSource(), }, }; }, });
// Express middleware expressMiddleware(server, { context: async ({ req, res }) => ({ token: req.headers.authorization, user: await getUser(req.headers.authorization), dataSources: { usersAPI: new UsersDataSource(), postsAPI: new PostsDataSource(), }, }), });
Reference Files
Detailed documentation for specific topics:
Resolvers - Resolver patterns and best practices Context and Auth - Authentication and authorization Plugins - Server and request lifecycle hooks Data Sources - RESTDataSource and DataLoader Error Handling - GraphQLError and error formatting Troubleshooting - Common issues and solutions Key Rules Schema Design Use ! (non-null) for fields that always have values Prefer input types for mutations over inline arguments Use interfaces for polymorphic types Keep schema descriptions for documentation Resolver Best Practices Keep resolvers thin - delegate to services/data sources Always handle errors explicitly Use DataLoader for batching related queries Return partial data when possible (GraphQL's strength) Performance Use @defer and @stream for large responses Implement DataLoader to solve N+1 queries Consider persisted queries for production Use caching headers and CDN where appropriate Ground Rules ALWAYS use Apollo Server 4.x patterns (not v3 or earlier) ALWAYS type your context with TypeScript generics ALWAYS use GraphQLError from graphql package for errors NEVER expose stack traces in production errors PREFER startStandaloneServer for simple setups USE expressMiddleware with drain plugin for Express apps IMPLEMENT authentication in context, authorization in resolvers