orcaqubits/graphql-dev

GraphQL Development for Saleor

Before writing code

Fetch live docs:

1. Web-search site:docs.saleor.io api-reference for the current Saleor GraphQL schema and API reference
2. Web-search site:the-guild.dev graphql-codegen for GraphQL Code Generator configuration and plugins
3. Web-search site:graphql.org learn for GraphQL specification fundamentals
4. Web-search saleor GraphQL TypedDocumentNode urql for typed client patterns
5. Fetch https://docs.saleor.io/docs/developer/api-conventions for Saleor-specific GraphQL conventions

GraphQL Fundamentals

| Operation | Purpose | Saleor Example | |-----------|---------|----------------| | Query | Read data | Fetch products, orders, categories | | Mutation | Write data | Create checkout, update product, complete order | | Subscription | Real-time events | Webhook subscription payloads |

Saleor API Characteristics

• GraphQL is the only API — there are no REST endpoints
• All operations are accessed at a single /graphql/ endpoint
• Mutations return both the result object and an errors array
• Queries support filtering, sorting, and cursor-based pagination
• Channel context is set via the channel argument or HTTP header

Fragments for Reuse

| Fragment Use Case | Benefit | |-------------------|---------| | Product fields | Reuse across product list, detail, and search queries | | Address fields | Share between checkout, order, and customer queries | | Money fields | Consistent currency/amount selection | | Error fields | Uniform error handling across mutations | | Image fields | Consistent image URL and alt text selection |

• Name fragments as {TypeName}Fragment (e.g., ProductFragment, AddressFragment)
• Keep fragments focused on a single concern
• Co-locate fragments with the components that use them

Variables and Input Types

| Concept | Description | Example | |---------|-------------|---------| | Variable | Dynamic value passed to operation | $id: ID!, $channel: String! | | Input type | Structured input for mutations | ProductCreateInput, CheckoutCreateInput | | Required | Non-null variable | $id: ID! (with !) | | Optional | Nullable variable | $filter: ProductFilterInput | | Default | Variable with default value | $first: Int = 10 |

• Always use variables instead of string interpolation for dynamic values
• Pass channel as a variable for multi-channel operations

GraphQL Code Generation

| Package | Purpose | |---------|---------| | @graphql-codegen/cli | Code generation CLI | | @graphql-codegen/typescript | Generate TypeScript types from schema | | @graphql-codegen/typescript-operations | Generate types for operations | | @graphql-codegen/typed-document-node | Generate TypedDocumentNode objects |

Configuration (codegen.ts)

| Setting | Value | Description | |---------|-------|-------------| | schema | Saleor GraphQL endpoint URL | Source of truth for types | | documents | "src/**/*.graphql" or "src/**/*.ts" | Location of operations | | generates | Output file paths | Where to write generated code | | plugins | Array of codegen plugins | Which code to generate |

• Run graphql-codegen after schema changes or when adding new operations
• Commit generated files to version control for CI consistency

TypedDocumentNode Pattern

| Aspect | Benefit | |--------|---------| | Query result | Fully typed response data | | Variables | Type-checked at compile time | | Fragments | Types flow through fragment composition | | IDE support | Autocomplete for fields and variables | | Refactoring | Rename detection across operations |

• Generated by @graphql-codegen/typed-document-node
• Works with urql, Apollo Client, and other GraphQL clients
• Catches schema mismatches at compile time, not runtime

Error Handling

| Error Type | Location | Cause | |-----------|----------|-------| | GraphQL errors | response.data.mutation.errors[] | Validation, permission, business logic | | Network errors | Caught by client | Connection failure, timeout, 5xx | | Schema errors | Build-time (codegen) | Operation doesn't match schema |

Saleor Mutation Error Structure

| Field | Type | Description | |-------|------|-------------| | field | String | Which input field caused the error | | message | String | Human-readable error message | | code | Enum | Machine-readable error code |

• Always check data.mutation.errors after every mutation
• Map error codes to user-friendly messages in the storefront

Client Libraries

| Client | Package | SSR Support | Caching | Best For | |--------|---------|-------------|---------|----------| | urql | @urql/core, @urql/next | Yes (via @urql/next) | Document cache, Graphcache | Saleor recommended | | Apollo Client | @apollo/client | Yes | Normalized cache | Complex caching needs | | graphql-request | graphql-request | N/A (no cache) | None | Simple scripts, server-side | | gql (Python) | gql | N/A | None | Python scripts and tests |

• Include Authorization: Bearer <token> header for authenticated operations
• Include saleor-channel: <slug> header for channel-scoped queries
• For SSR: ensure proper request deduplication and cache hydration

Operation Naming Conventions

| Convention | Example | Benefit | |-----------|---------|---------| | Prefix with verb | GetProducts, CreateCheckout | Clear intent | | Suffix queries | ProductListQuery, OrderDetailQuery | Distinguish from mutations | | Suffix mutations | CheckoutCreateMutation | Distinguish from queries | | Unique names | No duplicates across codebase | Required by codegen |

Pagination Patterns

Saleor uses Relay-style cursor-based pagination:

| Parameter | Type | Description | |-----------|------|-------------| | first | Int | Number of items from the start | | after | String | Cursor after which to fetch | | last | Int | Number of items from the end | | before | String | Cursor before which to fetch |

Response Structure

| Field | Path | Description | |-------|------|-------------| | edges | connection.edges[] | Array of edge objects | | node | edge.node | The actual entity | | cursor | edge.cursor | Opaque cursor string | | pageInfo.hasNextPage | connection.pageInfo | More items forward | | totalCount | connection.totalCount | Total items matching filter |

• Use first + after for forward pagination (most common)
• Avoid using totalCount for large datasets (can be slow)

Introspection and Schema Downloading

| Method | Tool | Use Case | |--------|------|----------| | Introspection query | Built-in GraphQL client | Development exploration | | GraphQL Playground | /graphql/ in browser | Interactive schema browser | | Schema download | graphql-codegen | CI/CD and type generation | | SDL export | rover graph introspect <url> | Save schema as .graphql file |

Testing GraphQL Operations

| Test Type | Tool | What to Test | |-----------|------|-------------| | Unit | Vitest, Jest | Operation result parsing, error mapping | | Integration | Saleor test instance | Full round-trip query/mutation | | Type check | tsc --noEmit | Generated types match operations | | Linting | @graphql-eslint/eslint-plugin | Operation naming, fragment usage |

Best Practices

• Use GraphQL code generation with TypedDocumentNode for end-to-end type safety
• Define reusable fragments for common field selections
• Always use variables for dynamic values — never concatenate strings
• Check data.mutation.errors after every mutation call
• Name every operation uniquely with descriptive PascalCase names
• Use cursor-based pagination with first/after for list queries
• Include the saleor-channel header for channel-scoped operations
• Keep operations minimal — request only the fields you need
• Run graphql-codegen in CI to catch schema mismatches

Fetch the GraphQL documentation for current Saleor schema, code generation setup, and client library configuration before implementing.