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/api-usage/overview for Saleor-specific GraphQL conventions

GraphQL Fundamentals

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

• 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

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

GraphQL Code Generation

Configuration (codegen.ts)

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

TypedDocumentNode Pattern

• 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

Saleor Mutation Error Structure

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

Client Libraries

• 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

Pagination Patterns

Saleor uses Relay-style cursor-based pagination:

Response Structure

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

Introspection and Schema Downloading

Testing GraphQL Operations

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.