Graphql

---
name: graphql
description: "GraphQL covering schema design, type system, execution model, Apollo Server/Client, Federation 2.x, Relay, DataLoader, persisted queries, subscriptions, and performance optimization. Use for \"GraphQL\", \"Apollo Server\", \"Apollo Client\", \"Federation\", \"subgraph\", \"supergraph\", \"DataLoader\", \"N+1\", \"schema design\", \"SDL\", \"resolver\", \"mutation\", \"subscription\", \"Relay\", \"Strawberry\", \"Hot Chocolate\", \"Mercurius\", \"graphql-yoga\", \"persisted queries\", \"introspection\", \"GraphQL Codegen\", \"Pothos\", \"TypeGraphQL\". Do NOT use for framework-specific integration details (e.g. wiring a resolver into an existing Express or Django app) — use the relevant framework skill in the `backend` plugin for that."
license: MIT
---

# GraphQL

This skill covers GraphQL, the query language for APIs. GraphQL is spec-based (October 2021 stable, with ongoing draft features). It has deep knowledge of:

- Type system (scalars, objects, interfaces, unions, enums, inputs)
- Execution model (parsing, validation, execution, null propagation)
- Schema design (schema-first vs code-first, Relay connections, input types)
- Server implementations (Apollo Server 5, Mercurius, graphql-yoga, Strawberry, Hot Chocolate)
- Apollo Client normalized cache, fetch policies, optimistic UI
- Federation 2.x (subgraphs, entity resolution, Rover CLI, Apollo Router)
- DataLoader pattern for N+1 prevention
- Subscriptions (WebSocket and SSE transport)
- Persisted queries, caching, and security hardening

## How to Approach Tasks

When you receive a request:

1. **Classify** the request:
   - **Schema design / type system** -- Load `references/architecture.md` for type system, execution model, schema patterns
   - **Performance / best practices** -- Load `references/best-practices.md` for DataLoader, caching, Federation, security, error handling
   - **Troubleshooting / diagnostics** -- Load `references/diagnostics.md` for N+1 queries, validation errors, cache issues, subscription problems
   - **Cross-protocol comparison** -- Read the `overview` skill for GraphQL vs REST, gRPC, etc.

2. **Gather context** -- Server library, client library, schema approach (SDL vs code-first), federation vs monolith, client platform

3. **Analyze** -- Apply GraphQL-specific reasoning. Consider schema evolution, query complexity, resolver architecture, and caching implications.

4. **Recommend** -- Provide actionable guidance with SDL snippets, resolver examples, and server configuration.

5. **Verify** -- Suggest validation steps (introspection queries, GraphQL Playground testing, Rover schema checks).

## Core Architecture

### Type System

Six named type kinds: Scalar (Int, Float, String, Boolean, ID + custom), Object, Interface, Union, Enum, Input. Wrapping types: Non-Null (`!`) and List (`[]`). Non-null on arguments means required.

### Execution Model

1. **Lexing** -- query string tokenized
2. **Parsing** -- tokens parsed into AST
3. **Validation** -- AST validated against schema (field existence, type compatibility, argument types)
4. **Execution** -- resolver tree traversed; sibling query fields resolve concurrently; root mutation fields execute serially

### Resolver Signature

```js
function resolver(parent, args, context, info) { }
```

`parent`: resolved value of parent field. `args`: field arguments. `context`: shared per-request (DB, loaders, user). `info`: field name, return type, schema, path.

### Schema-First vs Code-First

| Approach | Advantages | Libraries |
|---|---|---|
| Schema-first (SDL) | Readable contract, federation-compatible | graphql-tools, Apollo Server |
| Code-first | Type safety, single source of truth | Pothos, Nexus, TypeGraphQL, Strawberry, Hot Chocolate |

### Key Server Implementations

| Library | Language | Performance | Notes |
|---|---|---|---|
| Apollo Server 5 | Node.js | Standard | Most popular, rich plugin ecosystem |
| Mercurius | Node.js (Fastify) | 70,000+ req/s (JIT) | Highest throughput Node.js server |
| graphql-yoga | Node.js/Deno/Bun | ~10,900 req/s | Framework-agnostic, Fetch API |
| Strawberry | Python | Standard | Type hints, FastAPI integration |
| Hot Chocolate | .NET | High | Attributes, EF Core projections |

## Anti-Patterns

1. **Not using DataLoader** -- Every list with related fields needs DataLoader. Without it, N items cause N database queries.
2. **Sharing DataLoader across requests** -- DataLoaders must be per-request. Sharing causes stale data and security leaks.
3. **No query depth/complexity limits** -- A single deeply-nested query can bring down the server. Set limits in production.
4. **Introspection enabled in production** -- Unless required for tooling, disable introspection to prevent schema exposure.
5. **Mutations without input types** -- Use `input CreatePostInput` instead of individual arguments. Cleaner, more evolvable.
6. **Removing fields without deprecation** -- Use `@deprecated(reason: "...")` with a 90-180 day migration period before removal.
7. **N+1 via nested pagination** -- Paginated connections inside lists are especially vulnerable. Batch at the DataLoader level.
8. **Returning raw database errors** -- Sanitize errors. Use `extensions.code` for machine-readable error classification.

## Reference Files

- `references/architecture.md` -- Type system, execution model, schema design, Relay connections, Federation 2.x architecture, subscription model, server implementations
- `references/best-practices.md` -- DataLoader pattern, caching (APQ, normalized cache), Federation best practices, security hardening, error handling, schema evolution, performance tuning
- `references/diagnostics.md` -- N+1 detection, validation errors, null propagation issues, cache problems, subscription failures, Federation composition errors

## Cross-References

- `overview` skill -- cross-protocol comparisons
- `websocket` skill -- WebSocket transport for GraphQL subscriptions

## Diagnostic Scripts

Ready-made endpoint-audit script (read-only introspection) in `scripts/`.

- `scripts/01-schema-introspection-audit.sh` -- Introspection exposure check and schema surface review