1---2name: graphql-dev3description: Write GraphQL queries, mutations, and subscriptions — fragments, code generation, TypedDocumentNode, variables, error handling, and client setup. Use when writing GraphQL code for Saleor.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/graphql-dev7---89# GraphQL Development for Saleor1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.saleor.io api-reference` for the current Saleor GraphQL schema and API reference152. Web-search `site:the-guild.dev graphql-codegen` for GraphQL Code Generator configuration and plugins163. Web-search `site:graphql.org learn` for GraphQL specification fundamentals174. Web-search `saleor GraphQL TypedDocumentNode urql` for typed client patterns185. Fetch `https://docs.saleor.io/docs/developer/api-conventions` for Saleor-specific GraphQL conventions1920## GraphQL Fundamentals2122| Operation | Purpose | Saleor Example |23|-----------|---------|----------------|24| **Query** | Read data | Fetch products, orders, categories |25| **Mutation** | Write data | Create checkout, update product, complete order |26| **Subscription** | Real-time events | Webhook subscription payloads |2728### Saleor API Characteristics2930- GraphQL is the **only** API — there are no REST endpoints31- All operations are accessed at a single `/graphql/` endpoint32- Mutations return both the result object and an `errors` array33- Queries support filtering, sorting, and cursor-based pagination34- Channel context is set via the `channel` argument or HTTP header3536## Fragments for Reuse3738| Fragment Use Case | Benefit |39|-------------------|---------|40| **Product fields** | Reuse across product list, detail, and search queries |41| **Address fields** | Share between checkout, order, and customer queries |42| **Money fields** | Consistent currency/amount selection |43| **Error fields** | Uniform error handling across mutations |44| **Image fields** | Consistent image URL and alt text selection |4546- Name fragments as `{TypeName}Fragment` (e.g., `ProductFragment`, `AddressFragment`)47- Keep fragments focused on a single concern48- Co-locate fragments with the components that use them4950## Variables and Input Types5152| Concept | Description | Example |53|---------|-------------|---------|54| **Variable** | Dynamic value passed to operation | `$id: ID!`, `$channel: String!` |55| **Input type** | Structured input for mutations | `ProductCreateInput`, `CheckoutCreateInput` |56| **Required** | Non-null variable | `$id: ID!` (with `!`) |57| **Optional** | Nullable variable | `$filter: ProductFilterInput` |58| **Default** | Variable with default value | `$first: Int = 10` |5960- Always use variables instead of string interpolation for dynamic values61- Pass channel as a variable for multi-channel operations6263## GraphQL Code Generation6465| Package | Purpose |66|---------|---------|67| `@graphql-codegen/cli` | Code generation CLI |68| `@graphql-codegen/typescript` | Generate TypeScript types from schema |69| `@graphql-codegen/typescript-operations` | Generate types for operations |70| `@graphql-codegen/typed-document-node` | Generate TypedDocumentNode objects |7172### Configuration (codegen.ts)7374| Setting | Value | Description |75|---------|-------|-------------|76| `schema` | Saleor GraphQL endpoint URL | Source of truth for types |77| `documents` | `"src/**/*.graphql"` or `"src/**/*.ts"` | Location of operations |78| `generates` | Output file paths | Where to write generated code |79| `plugins` | Array of codegen plugins | Which code to generate |8081- Run `graphql-codegen` after schema changes or when adding new operations82- Commit generated files to version control for CI consistency8384## TypedDocumentNode Pattern8586| Aspect | Benefit |87|--------|---------|88| **Query result** | Fully typed response data |89| **Variables** | Type-checked at compile time |90| **Fragments** | Types flow through fragment composition |91| **IDE support** | Autocomplete for fields and variables |92| **Refactoring** | Rename detection across operations |9394- Generated by `@graphql-codegen/typed-document-node`95- Works with urql, Apollo Client, and other GraphQL clients96- Catches schema mismatches at compile time, not runtime9798## Error Handling99100| Error Type | Location | Cause |101|-----------|----------|-------|102| **GraphQL errors** | `response.data.mutation.errors[]` | Validation, permission, business logic |103| **Network errors** | Caught by client | Connection failure, timeout, 5xx |104| **Schema errors** | Build-time (codegen) | Operation doesn't match schema |105106### Saleor Mutation Error Structure107108| Field | Type | Description |109|-------|------|-------------|110| `field` | `String` | Which input field caused the error |111| `message` | `String` | Human-readable error message |112| `code` | `Enum` | Machine-readable error code |113114- Always check `data.mutation.errors` after every mutation115- Map error codes to user-friendly messages in the storefront116117## Client Libraries118119| Client | Package | SSR Support | Caching | Best For |120|--------|---------|-------------|---------|----------|121| **urql** | `@urql/core`, `@urql/next` | Yes (via `@urql/next`) | Document cache, Graphcache | Saleor recommended |122| **Apollo Client** | `@apollo/client` | Yes | Normalized cache | Complex caching needs |123| **graphql-request** | `graphql-request` | N/A (no cache) | None | Simple scripts, server-side |124| **gql** (Python) | `gql` | N/A | None | Python scripts and tests |125126- Include `Authorization: Bearer <token>` header for authenticated operations127- Include `saleor-channel: <slug>` header for channel-scoped queries128- For SSR: ensure proper request deduplication and cache hydration129130## Operation Naming Conventions131132| Convention | Example | Benefit |133|-----------|---------|---------|134| **Prefix with verb** | `GetProducts`, `CreateCheckout` | Clear intent |135| **Suffix queries** | `ProductListQuery`, `OrderDetailQuery` | Distinguish from mutations |136| **Suffix mutations** | `CheckoutCreateMutation` | Distinguish from queries |137| **Unique names** | No duplicates across codebase | Required by codegen |138139## Pagination Patterns140141Saleor uses Relay-style cursor-based pagination:142143| Parameter | Type | Description |144|-----------|------|-------------|145| `first` | `Int` | Number of items from the start |146| `after` | `String` | Cursor after which to fetch |147| `last` | `Int` | Number of items from the end |148| `before` | `String` | Cursor before which to fetch |149150### Response Structure151152| Field | Path | Description |153|-------|------|-------------|154| **edges** | `connection.edges[]` | Array of edge objects |155| **node** | `edge.node` | The actual entity |156| **cursor** | `edge.cursor` | Opaque cursor string |157| **pageInfo.hasNextPage** | `connection.pageInfo` | More items forward |158| **totalCount** | `connection.totalCount` | Total items matching filter |159160- Use `first` + `after` for forward pagination (most common)161- Avoid using `totalCount` for large datasets (can be slow)162163## Introspection and Schema Downloading164165| Method | Tool | Use Case |166|--------|------|----------|167| **Introspection query** | Built-in GraphQL client | Development exploration |168| **GraphQL Playground** | `/graphql/` in browser | Interactive schema browser |169| **Schema download** | `graphql-codegen` | CI/CD and type generation |170| **SDL export** | `rover graph introspect <url>` | Save schema as `.graphql` file |171172## Testing GraphQL Operations173174| Test Type | Tool | What to Test |175|-----------|------|-------------|176| **Unit** | Vitest, Jest | Operation result parsing, error mapping |177| **Integration** | Saleor test instance | Full round-trip query/mutation |178| **Type check** | `tsc --noEmit` | Generated types match operations |179| **Linting** | `@graphql-eslint/eslint-plugin` | Operation naming, fragment usage |180181## Best Practices182183- Use GraphQL code generation with TypedDocumentNode for end-to-end type safety184- Define reusable fragments for common field selections185- Always use variables for dynamic values — never concatenate strings186- Check `data.mutation.errors` after every mutation call187- Name every operation uniquely with descriptive PascalCase names188- Use cursor-based pagination with `first`/`after` for list queries189- Include the `saleor-channel` header for channel-scoped operations190- Keep operations minimal — request only the fields you need191- Run `graphql-codegen` in CI to catch schema mismatches192193Fetch the GraphQL documentation for current Saleor schema, code generation setup, and client library configuration before implementing.