graphql
GraphQL schema design, resolver patterns, subscriptions, DataLoader batching, federation, and security best practices
SKILL.md.claude/skills/graphql/SKILL.md
GitHubGraphQL Domain Skill
Purpose
Provide expert-level guidance on GraphQL schema design, resolver implementation, subscriptions, DataLoader for N+1 prevention, schema federation, security hardening, and production optimization patterns.
Key Patterns
1. Schema Design Principles
# Use Relay-style connections for pagination
type Query {
"""List users with cursor-based pagination."""
users(
first: Int
after: String
last: Int
before: String
filter: UserFilter
orderBy: UserOrderBy
): UserConnection!
"""Get a single user by ID."""
user(id: ID!): User
"""Get the currently authenticated user."""
me: User
}
type Mutation {
"""Create a new user account."""
createUser(input: CreateUserInput!): CreateUserPayload!
"""Update user profile fields."""
updateUser(input: UpdateUserInput!): UpdateUserPayload!
"""Delete a user account (soft delete)."""
deleteUser(id: ID!): DeleteUserPayload!
}
type Subscription {
"""Subscribe to new messages in a channel."""
messageReceived(channelId: ID!): Message!
}
# Input types for mutations
input CreateUserInput {
email: String!
name: String!
role: UserRole = MEMBER
}
# Payload types with userErrors for client-safe errors
type CreateUserPayload {
user: User
userErrors: [UserError!]!
}
type UserError {
field: [String!]
message: String!
code: ErrorCode!
}
enum ErrorCode {
INVALID_INPUT
NOT_FOUND
ALREADY_EXISTS
UNAUTHORIZED
}
# Relay connection types
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type UserEdge {
node: User!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# Interfaces for shared types
interface Node {
id: ID!
}
interface Timestamped {
createdAt: DateTime!
updatedAt: DateTime!
}
type User implements Node & Timestamped {
id: ID!
email: String!
name: String!
role: UserRole!
posts(first: Int, after: String): PostConnection!
createdAt: DateTime!
updatedAt: DateTime!
}
enum UserRole {
ADMIN
MEMBER
VIEWER
}
# Custom scalars
scalar DateTime
scalar JSON
scalar EmailAddress
2. Resolver Patterns (Node.js / TypeScript)
import { GraphQLResolveInfo } from 'graphql';
import DataLoader from 'dataloader';
// Context type
interface Context {
currentUser: User | null;
loaders: ReturnType<typeof createLoaders>;
db: Database;
}
// DataLoader factory -- create per-request to prevent caching across users
function createLoaders(db: Database) {
return {
user: new DataLoader<string, User | null>(async (ids) => {
const users = await db.user.findMany({ where: { id: { in: [...ids] } } });
const userMap = new Map(users.map(u => [u.id, u]));
return ids.map(id => userMap.get(id) ?? null);
}),
userPosts: new DataLoader<string, Post[]>(async (userIds) => {
const posts = await db.post.findMany({
where: { authorId: { in: [...userIds] } },
});
const grouped = groupBy(posts, 'authorId');
return userIds.map(id => grouped[id] ?? []);
}),
};
}
// Resolvers
const resolvers = {
Query: {
me: (_parent: unknown, _args: unknown, ctx: Context) => {
return ctx.currentUser;
},
users: async (_parent: unknown, args: ConnectionArgs, ctx: Context) => {
requireAuth(ctx);
return paginateConnection(ctx.db.user, args);
},
user: async (_parent: unknown, args: { id: string }, ctx: Context) => {
return ctx.loaders.user.load(args.id);
},
},
Mutation: {
createUser: async (_parent: unknown, args: { input: CreateUserInput }, ctx: Context) => {
requireRole(ctx, 'ADMIN');
const existing = await ctx.db.user.findUnique({ where: { email: args.input.email } });
if (existing) {
return {
user: null,
userErrors: [{ field: ['email'], message: 'Email already registered', code: 'ALREADY_EXISTS' }],
};
}
const user = await ctx.db.user.create({ data: args.input });
return { user, userErrors: [] };
},
},
User: {
// Field-level resolver with DataLoader
posts: (parent: User, args: ConnectionArgs, ctx: Context) => {
return ctx.loaders.userPosts.load(parent.id);
},
},
Subscription: {
messageReceived: {
subscribe: (_parent: unknown, args: { channelId: string }, ctx: Context) => {
requireAuth(ctx);
return ctx.pubsub.asyncIterator(`CHANNEL_${args.channelId}`);
},
},
},
};
3. Connection/Pagination Helper
interface ConnectionArgs {
first?: number | null;
after?: string | null;
last?: number | null;
before?: string | null;
}
async function paginateConnection<T extends { id: string }>(
model: PrismaModel<T>,
args: ConnectionArgs,
where?: Record<string, unknown>,
) {
const limit = args.first ?? args.last ?? 20;
const clampedLimit = Math.min(limit, 100);
let cursor: string | undefined;
let direction: 'forward' | 'backward' = 'forward';
if (args.after) {
cursor = decodeCursor(args.after);
direction = 'forward';
} else if (args.before) {
cursor = decodeCursor(args.before);
direction = 'backward';
}
// Fetch one extra to determine hasNextPage/hasPreviousPage
const items = await model.findMany({
where: {
...where,
...(cursor ? { id: { [direction === 'forward' ? 'gt' : 'lt']: cursor } } : {}),
},
take: clampedLimit + 1,
orderBy: { id: direction === 'forward' ? 'asc' : 'desc' },
});
const hasMore = items.length > clampedLimit;
const nodes = hasMore ? items.slice(0, clampedLimit) : items;
if (direction === 'backward') nodes.reverse();
const totalCount = await model.count({ where });
return {
edges: nodes.map(node => ({
node,
cursor: encodeCursor(node.id),
})),
pageInfo: {
hasNextPage: direction === 'forward' ? hasMore : !!cursor,
hasPreviousPage: direction === 'backward' ? hasMore : !!cursor,
startCursor: nodes.length ? encodeCursor(nodes[0].id) : null,
endCursor: nodes.length ? encodeCursor(nodes[nodes.length - 1].id) : null,
},
totalCount,
};
}
4. Security
// Query depth limiting
import depthLimit from 'graphql-depth-limit';
const server = new ApolloServer({
schema,
validationRules: [depthLimit(10)],
plugins: [
// Query complexity analysis
createComplexityPlugin({
maximumComplexity: 1000,
defaultComplexity: 1,
estimators: [
fieldExtensionsEstimator(),
simpleEstimator({ defaultComplexity: 1 }),
],
onComplete: (complexity) => {
if (complexity > 500) {
logger.warn({ complexity }, 'High query complexity');
}
},
}),
],
});
// Disable introspection in production
const server = new ApolloServer({
introspection: process.env.NODE_ENV !== 'production',
});
// Rate limiting per operation
const rateLimitDirective = (limit: number, window: string) => {
return (next: Function) => async (root: any, args: any, ctx: Context, info: any) => {
const key = `ratelimit:${ctx.currentUser?.id}:${info.fieldName}`;
const current = await ctx.redis.incr(key);
if (current === 1) await ctx.redis.expire(key, parseWindow(window));
if (current > limit) throw new Error('Rate limit exceeded');
return next(root, args, ctx, info);
};
};
Best Practices
- Use Relay cursor-based pagination for all list fields
- Return payload types from mutations with
userErrorsarray, never throw for user errors - Use DataLoader for every relationship -- N+1 queries are the #1 GraphQL perf issue
- Create DataLoader instances per-request -- never share across requests
- Limit query depth (10 max) and complexity (1000 max)
- Use input types for mutation arguments -- never inline scalars
- Design nullable by default -- only mark
!when you can guarantee the field - Version via schema evolution -- add fields, deprecate old ones, never remove
- Use persisted queries in production to prevent arbitrary query injection
- Log and monitor resolver execution times per field
Common Pitfalls
| Pitfall | Impact | Fix |
|---|---|---|
| N+1 queries without DataLoader | Exponential DB load | DataLoader for every relationship resolver |
| Deeply nested queries | DoS via resource exhaustion | Depth limiting + complexity analysis |
| Over-fetching in resolvers | Slow responses | Check info.fieldNodes to resolve only requested fields |
| Throwing errors in mutations | Bad client experience | Return structured userErrors in payload types |
| Shared DataLoader across requests | Data leaks between users | Create new DataLoader per request in context |
| No introspection control | Schema exposure | Disable introspection in production |