GraphQL Development Workflow

This guide covers the day-to-day development workflow when working with GraphQL, including code generation, debugging, and troubleshooting common issues.

Codegen runs automatically when you start development:

When you save a .graphql file, codegen automatically:

For manual generation (rarely needed):

When the backend GraphQL schema changes:

The schema is fetched from:

To manually introspect and save the schema:

This updates:

For each .graphql file, codegen creates a .graphql.ts file:

Generated files are not committed to the repository:

This prevents:

Problem: Types not updating after schema change

If your IDE isn't showing proper types:

Error: Cannot find GetChatroomsDocument

The easiest way to catch issues before committing is to enable pre-commit hooks:

This configures git to automatically run linting and formatting checks before each commit. The hooks will run the necessary validation commands for you.

If you prefer to run checks manually, or if hooks aren't enabled:

Our GraphQL ESLint configuration helps maintain code quality by enforcing best practices and catching potential issues early. The rules are configured in turbo/packages/toolchain/eslint.config.base.mjs and apply to all .graphql files.

What it does: Limits the depth of nested field selections to prevent overly complex queries that can impact performance.

When to disable: Legitimate deep queries (e.g., audit logs, detailed reports, complex nested data structures).

How to fix:

Example:

What it does: Ensures fragments and operations have an id field selected if available. This is required for Apollo Client caching to work properly.

When to disable: Id isn't the index field for the object.

How to fix:

Example:

What it does: Warns when using deprecated fields or types that are scheduled for removal.

When to disable: Legacy code using deprecated fields that need migration to newer alternatives.

How to fix:

Example:

What it does: Prevents selecting the same field multiple times in a selection set.

How to fix: Remove duplicate field selections - this is usually a simple fix.

Example:

What it does: Enforces consistent naming conventions for operations, types, and fields.

How to fix: Rename operations/types to match our conventions:

Example:

When working in files with suppressions:

This automatically removes suppressions for violations that have been fixed.

✅ Do:

❌ Don't:

Check for GraphQL ESLint violations:

Run linting for affected packages only:

Prune obsolete suppressions:

Cause: Codegen hasn't run yet

Solution:

Cause: Using string instead of enum

Solution:

Cause: Missing fragment import in GraphQL file

Solution:

Cause: Processing too many files

Solutions:

Factory functions are exported from @prepared911/data-gql/factories, and document nodes are exported from @prepared911/data-gql:

Factory functions accept an optional overrides parameter to customize specific fields:

The most common use case is mocking GraphQL queries in component tests. Use renderWithMockedProvider from ~src/tests instead of manually setting up MockedProvider:

For testing custom hooks that use Apollo Client hooks (useQuery, useMutation, useSubscription), use renderHook from @testing-library/react with WithMockedProvider as the wrapper:

Key points for hook testing:

You can override any field, including nested relationships:

Factory functions work seamlessly with fragment types. When you use a fragment in a query, you can create mock data that matches the fragment structure:

When mocking query results, structure your mock data to match the query's return type:

Mutations work the same way as queries. Use factories for mutation payload types:

Subscriptions can be mocked the same way as queries and mutations:

Here's a complete example showing how to use factories in a real test with multiple operations and additional providers:

Key points from this example:

The codebase includes helper functions that combine factories with MockedProvider. Import from ~src/tests:

Common additional providers:

The renderWithMockedProvider helper automatically:

Install GraphQL extensions for your IDE:

Install browser extension for debugging:

Keep fragments close to their consumers:

Use Apollo Client's built-in logging:

To improve codegen speed:

This guide covered the practical aspects of working with GraphQL in the Prepared monorepo. Here's a quick reference of key concepts: