Home › GraphQL › GraphQL server (Apollo) rules

GraphQL server (Apollo) rules

Cursor rules for schema-first GraphQL servers with Apollo Server, codegen types, DataLoader, and safe errors.

CursorGraphQL

Copy graphql.mdc

How to use

Save this as .cursor/rules/graphql.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

---
description: GraphQL server (Apollo) conventions
globs: ["src/**/*.{ts,graphql}"]
alwaysApply: false
---

# GraphQL server (Apollo)

- Schema-first: edit `.graphql` files in `src/schema/`, then run `npm run codegen` (GraphQL Code Generator) to get resolver types. Resolvers are typed with the generated `Resolvers` type.
- Naming: types `PascalCase`, fields `camelCase`, enums `SCREAMING_SNAKE`. Mutations are verbs (`createPost`) taking one `input:` argument and returning a payload type.
- Lists that can grow use cursor pagination (`first`, `after`, `edges`, `pageInfo`).
- Resolvers stay thin: get the user and loaders from `context`, call a service.
- Batch every field that loads by id with DataLoader created per request in the context factory. No DB call inside a list item resolver without a loader.
- Authorization in the service or a directive, checked per field when data is sensitive; not only at the top-level query.
- Expected errors are `GraphQLError` with `extensions.code` (`UNAUTHENTICATED`, `FORBIDDEN`, `BAD_USER_INPUT`). Mask unexpected errors in production.
- Protect the server: depth/complexity limits, disable introspection in production if the API is private, persisted queries for public clients.
- Deprecate with `@deprecated(reason: ...)` instead of removing fields.

## Don't
- Don't change a field's type or nullability in place; add a new field.

## Done when
Codegen is clean, `tsc --noEmit` and resolver tests pass.