GraphQL Overview

The Prepared monorepo uses a unified GraphQL code generation approach to ensure type safety, maintainability, and developer productivity across all frontend applications.

Our GraphQL implementation follows these key principles:

Before diving into GraphQL in the Prepared monorepo, you should be familiar with:

If you're new to any of these, consider reviewing the relevant documentation first.

This GraphQL documentation is organized to follow a natural learning progression:

Each section builds on the previous one, so we recommend reading them in order.

The GraphQL schema serves as the single source of truth for both backend and frontend. Types, enums, and interfaces are all generated from this schema, ensuring consistency across the stack.

Using the near-operation-file preset, generated types are placed in the same folder as your .graphql files:

Instead of auto-generated hooks, we use typed document nodes with Apollo Client's useQuery, useMutation, and useSubscription hooks. This provides better flexibility and type safety.

Create a queries.graphql file next to your component:

Codegen runs automatically when you start development:

Codegen will automatically regenerate types when you modify .graphql files. For manual generation (rarely needed):

These rules help maintain clean, efficient GraphQL operations and prevent over-fetching.

✅ Do this:

❌ Don't do this:

✅ Do this:

❌ Don't do this:

The TypeScript compiler will catch type mismatches, ensuring your variables match the schema expectations.

Understanding where to import GraphQL-related types and values is crucial for maintaining proper code organization and leveraging the benefits of colocation. Our setup uses two primary import sources, each serving a specific purpose.

The centralized @prepared911/data-gql package contains shared, reusable types that are used across multiple components and operations:

These types are centralized because they represent shared concepts that don't belong to any single component or operation.

Component-level GraphQL files (colocated with your components) export operation-specific types and values:

These are colocated because they represent the data contract for a specific component or operation, making it easy to see what data a component needs.

Here's a practical example showing both import sources used together:

This import strategy provides several key benefits:

This documentation describes the new GraphQL pattern using colocated .graphql files. If you're working with code that uses the legacy centralized import pattern, here's how to migrate:

The legacy pattern will be removed after the migration is complete.