--- name: graphql-schema description: GraphQL queries, mutations, and code generation patterns. Use when creating GraphQL operations, working with Apollo Client, or generating types. --- # GraphQL Schema Patterns ## Core Rules 1. **NEVER inline `gql` literals** - Create `.gql` files 2. **ALWAYS run codegen** after creating\/modifying `.gql` files 3. **ALWAYS add `onError` handler** to mutations 4. **Use generated hooks** - Never write raw Apollo hooks ## File Structure ``` src\/ ├── components\/ │ └── ItemList\/ │ ├── ItemList.tsx │ ├── GetItems.gql # Query definition │ └── GetItems.generated.ts # Auto-generated (don't edit) └── graphql\/ └── mutations\/ └── CreateItem.gql # Shared mutations ``` ## Creating a Query ### Step 1: Create .gql file ```graphql # src\/components\/ItemList\/GetItems.gql query GetItems($limit: Int, $offset: Int) { items(limit: $limit, offset: $offset) { id name description createdAt } } ``` ### Step 2: Run codegen ```bash npm run gql:typegen ``` ### Step 3: Import and use generated hook ```typescript import { useGetItemsQuery } from '.\/GetItems.generated'; const ItemList = () => { const { data, loading, error, refetch } = useGetItemsQuery({ variables: { limit: 20, offset: 0 }, }); if (error) return ; if (loading && !data) return ; if (!data?.items.length) return ; return ; }; ``` ## Creating a Mutation ### Step 1: Create .gql file ```graphql # src\/graphql\/mutations\/CreateItem.gql mutation CreateItem($input: CreateItemInput!) { createItem(input: $input) { id name description } } ``` ### Step 2: Run codegen ```bash npm run gql:typegen ``` ### Step 3: Use with REQUIRED error handling ```typescript import { useCreateItemMutation } from 'graphql\/mutations\/CreateItem.generated'; const CreateItemForm = () => { const [createItem, { loading }] = useCreateItemMutation({ \/\/ Success handling onCompleted: (data) => { toast.success({ title: 'Item created' }); navigation.goBack(); }, \/\/ ERROR HANDLING IS REQUIRED onError: (error) => { console.error('createItem failed:', error); toast.error({ title: 'Failed to create item' }); }, \/\/ Cache update update: (cache, { data }) => { if (data?.createItem) { cache.modify({ fields: { items: (existing = []) => [...existing, data.createItem], }, }); } }, }); return (