# Graphql Schema

GraphQL queries, mutations, and code generation patterns.

- Repository: https://github.com/ChrisWiles/claude-code-showcase (6078 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-01-06
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ChrisWiles/claude-code-showcase --skill graphql-schema -g -a claude-code -y`
Codex: `npx skills add ChrisWiles/claude-code-showcase --skill graphql-schema -g -a codex -y`
Cursor: `npx skills add ChrisWiles/claude-code-showcase --skill graphql-schema -g -a cursor -y`
Gemini CLI: `npx skills add ChrisWiles/claude-code-showcase --skill graphql-schema -g -a gemini-cli -y`

## Description

GraphQL queries, mutations, and code generation patterns. Use when creating GraphQL operations, working with Apollo Client, or generating types.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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 <ErrorState error={error} onRetry={refetch} />;
  if (loading && !data) return <LoadingSkeleton />;
  if (!data?.items.length) return <EmptyState />;

  return <List items={data.items} />;
};
```

## 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';

The rest: https://github.com/ChrisWiles/claude-code-showcase/blob/HEAD/.claude/skills/graphql-schema/SKILL.md