api-graphql-apollo-server
GraphQL API server with Apollo Server — schema, resolvers, context, error handling, data sources, plugins
Install
npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-graphql-apollo-server/skills/api-graphql-apollo-server
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
git clone https://github.com/agents-inc/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
GraphQL API with Apollo Server
Quick Guide: Use
@apollo/server(v5) for schema-first GraphQL APIs. Define schemas with SDL (typeDefs), implement field population with resolvers, share per-request state via thecontextfunction, and handle errors withGraphQLError+ extension codes. UsestartStandaloneServerfor quick setups or integrate with your HTTP framework for production. DataLoader solves the N+1 problem. Plugins hook into the request lifecycle for logging, auth, and performance.
<critical_requirements>
CRITICAL: Before Using This Skill
(You MUST import from @apollo/server -- NOT the deprecated apollo-server or apollo-server-express packages)
(You MUST create new data source and DataLoader instances per request in the context function -- sharing across requests causes data leaks)
(You MUST throw GraphQLError (from graphql) with extension codes for client-facing errors -- generic Error exposes stack traces)
(You MUST use ApolloServerPluginDrainHttpServer when integrating with an HTTP framework -- without it the server doesn't shut down gracefully)
</critical_requirements>
Auto-detection: Apollo Server, @apollo/server, ApolloServer, startStandaloneServer, expressMiddleware, GraphQLError, typeDefs, resolvers, contextValue, DataLoader, RESTDataSource, @apollo/datasource-rest, ApolloServerPlugin, buildSubgraphSchema, @apollo/subgraph, graphql-ws, PubSub, formatError, gql tag
When to use:
- Building a GraphQL API with schema-first (SDL) design
- Defining typed resolvers with shared context (auth, data sources)
- Wrapping REST APIs or databases behind a unified GraphQL layer
- Implementing real-time features with subscriptions (via
graphql-ws) - Building federated subgraphs with
@apollo/subgraph - Adding lifecycle hooks with plugins (logging, auth, tracing)
When NOT to use:
- Simple REST APIs without nested data relationships (a REST framework is simpler)
- APIs consumed only by one client you control with no query flexibility needs
- Performance-critical APIs where schema overhead matters (consider a code-first approach)
Key patterns covered:
- Server setup with
startStandaloneServerand framework middleware integration - Resolver structure, arguments (
parent,args,contextValue,info), and chains - Context function for per-request state (auth tokens, data sources, DataLoaders)
- Error handling with
GraphQLError, built-in codes, andformatError - RESTDataSource for wrapping REST APIs with caching and deduplication
- DataLoader for batching and deduplication (N+1 problem)
- Custom plugins with server-level and request-level lifecycle hooks
- Subscriptions with
graphql-wsand WebSocket server - Federation subgraph setup with
@apollo/subgraph
Detailed Resources:
- examples/core.md - Server setup, resolvers, context, error handling
- examples/data-sources.md - RESTDataSource, DataLoader, caching
- examples/advanced.md - Subscriptions, federation, custom plugins
- reference.md - Decision frameworks, anti-patterns, production checklist
<red_flags>
RED FLAGS
High Priority:
- Importing from deprecated packages (
apollo-server,apollo-server-express) -- use@apollo/serverexclusively - Sharing data source or DataLoader instances across requests -- causes stale data and cross-user leaks; create new instances in the context function
- Throwing generic
Errorfrom resolvers -- exposes stack traces to clients; useGraphQLErrorwith extension codes - Missing
ApolloServerPluginDrainHttpServerwhen using framework integration -- server won't shut down gracefully, leaving connections hanging - Calling
expressMiddlewarebeforeserver.start()-- throws an error;start()must complete first
Medium Priority:
- Using
c.req.paramsinstead of resolverargs-- bypasses GraphQL argument validation - No pagination limits on list resolvers -- returns entire datasets; always enforce max limits
- In-memory
PubSubin production -- only works for a single server instance; use a distributed system - Missing
encodeURIComponenton dynamic URL segments in RESTDataSource -- path traversal vulnerability - Not using
formatErrorto sanitize errors -- internal error messages and stack traces leak to clients in development mode
Gotchas & Edge Cases:
- Default resolvers: Apollo Server auto-resolves fields matching property names on the parent object -- you don't need explicit resolvers for simple property access
contextValueis shared: Never destructively modifycontextValuein resolvers -- other resolvers in the same operation share the object- Resolver return value of
undefined: Triggers the default resolver to try accessing a property on the parent -- may cause unexpected behavior if the parent doesn't have that field - Introspection disabled in production: By default, introspection is off when
NODE_ENV=production-- override withintrospection: trueif needed - Variable coercion errors: In v5, malformed variables return HTTP 400 by default (v4 returned 200) -- existing clients may need updates
- Express integration in v5: Import
expressMiddlewarefrom@as-integrations/express4or@as-integrations/express5(not from@apollo/server/express4which was removed) - Subscription resolvers: Must return an
AsyncIteratorfromsubscribe, not a direct value -- theresolvefunction (optional) transforms the event payload - Plugin lifecycle: All plugin methods are async except
willResolveFieldandschemaDidLoadOrUpdate
</red_flags>
<critical_reminders>
CRITICAL REMINDERS
(You MUST import from @apollo/server -- NOT the deprecated apollo-server or apollo-server-express packages)
(You MUST create new data source and DataLoader instances per request in the context function -- sharing across requests causes data leaks)
(You MUST throw GraphQLError (from graphql) with extension codes for client-facing errors -- generic Error exposes stack traces)
(You MUST use ApolloServerPluginDrainHttpServer when integrating with an HTTP framework -- without it the server doesn't shut down gracefully)
Failure to follow these rules will cause data leaks between users, expose internal errors to clients, and prevent graceful shutdown.
</critical_reminders>
Files (skills)
-
examples
-
advanced.md 13.4 KB
Loading… -
core.md 13.3 KB
Loading… -
data-sources.md 10 KB
Loading…
-
-
reference.md 9.7 KB
Loading… -
SKILL.md 14.4 KB
--- name: api-graphql-apollo-server description: GraphQL API server with Apollo Server — schema, resolvers, context, error handling, data sources, plugins --- # GraphQL API with Apollo Server > **Quick Guide:** Use `@apollo/server` (v5) for schema-first GraphQL APIs. Define schemas with SDL (`typeDefs`), implement field population with resolvers, share per-request state via the `context` function, and handle errors with `GraphQLError` + extension codes. Use `startStandaloneServer` for quick setups or integrate with your HTTP framework for production. DataLoader solves the N+1 problem. Plugins hook into the request lifecycle for logging, auth, and performance. --- <critical_requirements> ## CRITICAL: Before Using This Skill **(You MUST import from `@apollo/server` -- NOT the deprecated `apollo-server` or `apollo-server-express` packages)** **(You MUST create new data source and DataLoader instances per request in the context function -- sharing across requests causes data leaks)** **(You MUST throw `GraphQLError` (from `graphql`) with extension codes for client-facing errors -- generic `Error` exposes stack traces)** **(You MUST use `ApolloServerPluginDrainHttpServer` when integrating with an HTTP framework -- without it the server doesn't shut down gracefully)** </critical_requirements> --- **Auto-detection:** Apollo Server, @apollo/server, ApolloServer, startStandaloneServer, expressMiddleware, GraphQLError, typeDefs, resolvers, contextValue, DataLoader, RESTDataSource, @apollo/datasource-rest, ApolloServerPlugin, buildSubgraphSchema, @apollo/subgraph, graphql-ws, PubSub, formatError, gql tag **When to use:** - Building a GraphQL API with schema-first (SDL) design - Defining typed resolvers with shared context (auth, data sources) - Wrapping REST APIs or databases behind a unified GraphQL layer - Implementing real-time features with subscriptions (via `graphql-ws`) - Building federated subgraphs with `@apollo/subgraph` - Adding lifecycle hooks with plugins (logging, auth, tracing) **When NOT to use:** - Simple REST APIs without nested data relationships (a REST framework is simpler) - APIs consumed only by one client you control with no query flexibility needs - Performance-critical APIs where schema overhead matters (consider a code-first approach) **Key patterns covered:** - Server setup with `startStandaloneServer` and framework middleware integration - Resolver structure, arguments (`parent`, `args`, `contextValue`, `info`), and chains - Context function for per-request state (auth tokens, data sources, DataLoaders) - Error handling with `GraphQLError`, built-in codes, and `formatError` - RESTDataSource for wrapping REST APIs with caching and deduplication - DataLoader for batching and deduplication (N+1 problem) - Custom plugins with server-level and request-level lifecycle hooks - Subscriptions with `graphql-ws` and WebSocket server - Federation subgraph setup with `@apollo/subgraph` **Detailed Resources:** - [examples/core.md](examples/core.md) - Server setup, resolvers, context, error handling - [examples/data-sources.md](examples/data-sources.md) - RESTDataSource, DataLoader, caching - [examples/advanced.md](examples/advanced.md) - Subscriptions, federation, custom plugins - [reference.md](reference.md) - Decision frameworks, anti-patterns, production checklist --- <philosophy> ## Philosophy Apollo Server follows a **schema-first** approach: define your API contract in SDL, then implement resolvers to populate each field. The schema is the single source of truth for your API shape, documentation, and type system. **Core principles:** 1. **Schema as contract** -- SDL defines what clients can query before implementation begins 2. **Thin resolvers** -- Resolvers orchestrate data fetching but delegate to data sources and services 3. **Per-request context** -- Each operation gets fresh data source instances and auth state via the context function 4. **Graceful error handling** -- `GraphQLError` with extension codes communicates errors without leaking internals **Use Apollo Server when:** - You need a unified API layer over multiple data sources (REST, DB, services) - Clients benefit from querying exactly the data they need (mobile, varied frontends) - Schema documentation and introspection matter for developer experience - You want lifecycle plugins for observability, auth, and caching **Use simpler approaches when:** - A single REST endpoint suffices for your use case - You have no nested data relationships worth expressing in a graph - The overhead of schema definition and resolver wiring doesn't justify the flexibility </philosophy> --- <patterns> ## Core Patterns ### Pattern 1: Server Setup Two approaches: `startStandaloneServer` for quick/simple setups, or framework middleware integration for production. ```typescript import { ApolloServer } from "@apollo/server"; import { startStandaloneServer } from "@apollo/server/standalone"; const server = new ApolloServer({ typeDefs, resolvers }); const DEFAULT_PORT = 4000; const { url } = await startStandaloneServer(server, { context: async ({ req }) => ({ token: req.headers.authorization, }), listen: { port: DEFAULT_PORT }, }); ``` **Why good:** minimal boilerplate for development, context function provides per-request auth state For production with an HTTP framework, use `expressMiddleware` (from `@as-integrations/express4` or `@as-integrations/express5`) with `ApolloServerPluginDrainHttpServer` for graceful shutdown. See [examples/core.md](examples/core.md) for both setup patterns with full TypeScript types. --- ### Pattern 2: Resolver Structure and Arguments Resolvers receive four arguments: `parent` (return value from parent resolver), `args` (field arguments), `contextValue` (shared per-request state), and `info` (operation metadata). ```typescript const resolvers = { Query: { user: async (_parent, args, contextValue) => { return contextValue.dataSources.usersAPI.getUser(args.id); }, }, User: { posts: async (parent, _args, contextValue) => { return contextValue.dataSources.postsAPI.getPostsByAuthor(parent.id); }, }, }; ``` **Why good:** parent chaining enables nested queries without client round-trips, data source access through context keeps resolvers thin See [examples/core.md](examples/core.md) for full resolver patterns with type safety. --- ### Pattern 3: Context Function The context function runs for every operation. Use it to create per-request data sources, extract auth, and set up DataLoaders. ```typescript interface MyContext { token: string | undefined; dataSources: { usersAPI: UsersAPI; postsAPI: PostsAPI; }; } const server = new ApolloServer<MyContext>({ typeDefs, resolvers }); ``` **Critical:** Create new data source instances per request. Sharing instances across requests causes stale data and leaks between users. See [examples/core.md](examples/core.md) for complete context setup. --- ### Pattern 4: Error Handling with GraphQLError Throw `GraphQLError` (from the `graphql` package) with extension codes for structured client errors. Use `formatError` to sanitize errors before sending. ```typescript import { GraphQLError } from "graphql"; throw new GraphQLError("User not found", { extensions: { code: "USER_NOT_FOUND", argumentName: "id", }, }); ``` **Built-in codes** (from `ApolloServerErrorCode`): `GRAPHQL_PARSE_FAILED`, `GRAPHQL_VALIDATION_FAILED`, `BAD_USER_INPUT`, `INTERNAL_SERVER_ERROR`, `BAD_REQUEST`, `PERSISTED_QUERY_NOT_FOUND`. See [examples/core.md](examples/core.md) for `formatError`, custom codes, and auth error patterns. --- ### Pattern 5: RESTDataSource Wrap REST APIs with `@apollo/datasource-rest` for built-in caching, request deduplication, and HTTP method helpers. ```typescript import { RESTDataSource } from "@apollo/datasource-rest"; class MoviesAPI extends RESTDataSource { override baseURL = "https://movies-api.example.com/"; async getMovie(id: string): Promise<Movie> { return this.get<Movie>(`movies/${encodeURIComponent(id)}`); } } ``` **Two-layer caching:** (1) request deduplication prevents duplicate GET calls within a single operation, (2) HTTP response caching honors `cache-control` headers. See [examples/data-sources.md](examples/data-sources.md) for RESTDataSource methods, custom caching, and `willSendRequest`. --- ### Pattern 6: DataLoader for N+1 Prevention Use DataLoader to batch and deduplicate database or API calls within a single GraphQL operation. ```typescript import DataLoader from "dataloader"; const userLoader = new DataLoader<string, User>(async (ids) => { const users = await db.users.findMany({ where: { id: { in: [...ids] } } }); return ids.map( (id) => users.find((u) => u.id === id) ?? new Error(`User ${id} not found`), ); }); ``` **Critical:** Create new DataLoader instances per request (in the context function). DataLoader caches results for the request lifetime -- sharing across requests serves stale data. See [examples/data-sources.md](examples/data-sources.md) for DataLoader setup, batching patterns, and integration with context. --- ### Pattern 7: Custom Plugins Plugins hook into server and request lifecycle events. Use them for logging, auth checks, performance tracing, and error reporting. ```typescript import type { ApolloServerPlugin } from "@apollo/server"; const loggingPlugin: ApolloServerPlugin<MyContext> = { async requestDidStart(requestContext) { const start = Date.now(); return { async willSendResponse() { const duration = Date.now() - start; console.log(`Operation took ${duration}ms`); }, }; }, }; ``` **Key lifecycle events:** `serverWillStart`, `requestDidStart`, `parsingDidStart`, `validationDidStart`, `executionDidStart`, `didEncounterErrors`, `willSendResponse`. See [examples/advanced.md](examples/advanced.md) for complete plugin patterns. --- ### Pattern 8: Subscriptions with graphql-ws Apollo Server does not include a built-in WebSocket transport. Use `graphql-ws` + `ws` for real-time subscriptions alongside your HTTP server. ```typescript import { WebSocketServer } from "ws"; import { useServer } from "graphql-ws/use/ws"; const wsServer = new WebSocketServer({ server: httpServer, path: "/subscriptions", }); const serverCleanup = useServer({ schema }, wsServer); ``` **Note:** `startStandaloneServer` does not support subscriptions -- use framework middleware integration instead. The in-memory `PubSub` from `graphql-subscriptions` is for development only; use a distributed pub/sub system in production. See [examples/advanced.md](examples/advanced.md) for complete subscription setup with drain plugins. --- ### Pattern 9: Federation Subgraph Use `@apollo/subgraph` to build a subgraph that participates in a federated supergraph. Entities use `@key` directives and `__resolveReference` resolvers. ```typescript import { buildSubgraphSchema } from "@apollo/subgraph"; const server = new ApolloServer({ schema: buildSubgraphSchema({ typeDefs, resolvers }), }); ``` **Key concepts:** `@key` designates entity identity fields, `__resolveReference` fetches entities by their key fields, `extend type` contributes fields from other subgraphs. See [examples/advanced.md](examples/advanced.md) for federation schema and reference resolver patterns. </patterns> --- <red_flags> ## RED FLAGS **High Priority:** - **Importing from deprecated packages** (`apollo-server`, `apollo-server-express`) -- use `@apollo/server` exclusively - **Sharing data source or DataLoader instances across requests** -- causes stale data and cross-user leaks; create new instances in the context function - **Throwing generic `Error` from resolvers** -- exposes stack traces to clients; use `GraphQLError` with extension codes - **Missing `ApolloServerPluginDrainHttpServer`** when using framework integration -- server won't shut down gracefully, leaving connections hanging - **Calling `expressMiddleware` before `server.start()`** -- throws an error; `start()` must complete first **Medium Priority:** - **Using `c.req.params` instead of resolver `args`** -- bypasses GraphQL argument validation - **No pagination limits on list resolvers** -- returns entire datasets; always enforce max limits - **In-memory `PubSub` in production** -- only works for a single server instance; use a distributed system - **Missing `encodeURIComponent` on dynamic URL segments in RESTDataSource** -- path traversal vulnerability - **Not using `formatError` to sanitize errors** -- internal error messages and stack traces leak to clients in development mode **Gotchas & Edge Cases:** - **Default resolvers:** Apollo Server auto-resolves fields matching property names on the parent object -- you don't need explicit resolvers for simple property access - **`contextValue` is shared:** Never destructively modify `contextValue` in resolvers -- other resolvers in the same operation share the object - **Resolver return value of `undefined`:** Triggers the default resolver to try accessing a property on the parent -- may cause unexpected behavior if the parent doesn't have that field - **Introspection disabled in production:** By default, introspection is off when `NODE_ENV=production` -- override with `introspection: true` if needed - **Variable coercion errors:** In v5, malformed variables return HTTP 400 by default (v4 returned 200) -- existing clients may need updates - **Express integration in v5:** Import `expressMiddleware` from `@as-integrations/express4` or `@as-integrations/express5` (not from `@apollo/server/express4` which was removed) - **Subscription resolvers:** Must return an `AsyncIterator` from `subscribe`, not a direct value -- the `resolve` function (optional) transforms the event payload - **Plugin lifecycle:** All plugin methods are async except `willResolveField` and `schemaDidLoadOrUpdate` </red_flags> --- <critical_reminders> ## CRITICAL REMINDERS **(You MUST import from `@apollo/server` -- NOT the deprecated `apollo-server` or `apollo-server-express` packages)** **(You MUST create new data source and DataLoader instances per request in the context function -- sharing across requests causes data leaks)** **(You MUST throw `GraphQLError` (from `graphql`) with extension codes for client-facing errors -- generic `Error` exposes stack traces)** **(You MUST use `ApolloServerPluginDrainHttpServer` when integrating with an HTTP framework -- without it the server doesn't shut down gracefully)** **Failure to follow these rules will cause data leaks between users, expose internal errors to clients, and prevent graceful shutdown.** </critical_reminders>
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.