graphql-workflow

What this skill does

# GraphQL Workflow Skill

This skill provides a generic, project-agnostic workflow for GraphQL development with automatic code generation. The core pattern is **role-based file naming** which enables type-safe, permission-aware GraphQL operations.

## When This Skill Activates

Claude automatically uses this skill when you:

- Create a new GraphQL query, mutation, or subscription
- Modify existing GraphQL operations
- Troubleshoot GraphQL codegen errors
- Regenerate types after schema changes
- Validate GraphQL file naming conventions
- Need to understand role-based GraphQL structure

## The Core Pattern: Role-Based File Naming

The key insight is that **GraphQL operations should be organized by permission role**, not by feature or operation type.

```
operationName.role.graphql
```

### Example Role Hierarchy

```
public < user < employee < admin
```

**Your project's roles may differ.** Common patterns:

| Project Type | Typical Roles |
|--------------|---------------|
| SaaS App | `public`, `user`, `admin` |
| Marketplace | `public`, `buyer`, `seller`, `admin` |
| Social Platform | `public`, `member`, `moderator`, `admin` |
| E-commerce | `public`, `customer`, `staff`, `admin` |

## Critical Rules

**NEVER violate these rules when working with GraphQL:**

1. ❌ **NEVER edit files in `*/generated/` directories** - These are auto-generated
2. ✅ **ALWAYS follow `.{role}.graphql` naming convention** - One file per role
3. ✅ **ALWAYS run codegen after GraphQL changes** - Regenerate types
4. ✅ **ALWAYS verify GraphQL backend is running before codegen** - Services must be available
5. ✅ **ALWAYS place files in your project's GraphQL directory** - Configure your codegen

## Workflow Steps

### 1. Create GraphQL Operation

**Step 1: Determine Requirements**

- Operation name (camelCase, descriptive)
- User role (from your project's role hierarchy)
- Operation type (query, mutation, subscription)
- Required data fields

**Step 2: Create Properly Named File**

```bash
# File naming pattern: {operationName}.{role}.graphql
# Examples for a typical SaaS app:
src/graphql/getUserProfile.user.graphql
src/graphql/createAppointment.user.graphql
src/graphql/getAllUsers.admin.graphql
src/graphql/getPublicData.public.graphql
```

**Step 3: Write GraphQL Operation**

```graphql
# Query Example (getUserProfile.user.graphql)
query GetUserProfile($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
    profilePicture
  }
}

# Mutation Example (createAppointment.user.graphql)
mutation CreateAppointment($input: AppointmentInput!) {
  createAppointment(input: $input) {
    id
    scheduledAt
    status
  }
}

# Subscription Example (onUserUpdate.user.graphql)
subscription OnUserUpdate($userId: ID!) {
  userUpdated(userId: $userId) {
    id
    name
    updatedAt
  }
}
```

**Step 4: Verify Backend Availability**

```bash
# Check your GraphQL endpoint is running
curl -f {YOUR_GRAPHQL_ENDPOINT} || echo "Backend not available"

# For Hasura: curl http://localhost:8080/healthz
# For Apollo: curl http://localhost:4000/.well-known/apollo/server-health
```

### 2. Run Code Generation

**Your project's codegen command will vary.** Common patterns:

```bash
# GraphQL Codegen (codegen-ts / graphql-codegen)
pnpm codegen

# With codegen-ts config files:
pnpm codegen:user      # User role only
pnpm codegen:admin     # Admin role only

# Or with npm scripts:
npm run generate-types
npm run codegen
```

**Expected Output:**

- ✅ TypeScript types generated in `src/generated/` (or your configured output)
- ✅ React hooks auto-generated for each operation
- ✅ Full type safety for variables and responses

### 3. Verify Generated Code

```typescript
// Import generated hook in your component
import { useGetUserProfileQuery } from '@/generated/user';

// Use with full type safety
const { data, loading, error } = useGetUserProfileQuery({
  variables: { userId: currentUser.id },
});

// data is fully typed with autocomplete
const user = data?.user; // Type: User | undefined
```

### 4. Handle Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| "Backend not available" | GraphQL server not running | Start your GraphQL backend service |
| "GraphQL file not found" | Wrong directory or naming | Check file location and `.role.graphql` suffix |
| "Codegen failed with syntax error" | Invalid GraphQL syntax | Validate operation syntax and field names |
| "Generated types not updated" | Stale build cache | Delete `generated/` folder and rerun codegen |
| "Type X does not exist" | Schema mismatch | Check your GraphQL schema matches backend |

## GraphQL Operation Templates

### Query Template

```graphql
# src/graphql/{operationName}.{role}.graphql
query {OperationName}($param: Type!) {
  tableName(where: { field: { _eq: $param } }) {
    id
    field1
    field2
    relatedTable {
      id
      name
    }
  }
}
```

### Mutation Template

```graphql
# src/graphql/{operationName}.{role}.graphql
mutation {OperationName}($input: table_insert_input!) {
  insert_table_one(object: $input) {
    id
    field1
    field2
    created_at
  }
}
```

### Subscription Template

```graphql
# src/graphql/{operationName}.{role}.graphql
subscription {OperationName}($userId: ID!) {
  tableName(where: { user_id: { _eq: $userId } }) {
    id
    field1
    updated_at
  }
}
```

## Integration with Components

**Step 1: Import Generated Hook**

```typescript
import { useGetUserProfileQuery } from '@/generated/user';
```

**Step 2: Use in Component**

```typescript
export function UserProfile({ userId }: { userId: string }) {
  const { data, loading, error } = useGetUserProfileQuery({
    variables: { userId }
  });

  if (loading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <div>
      <h1>{data?.user?.name}</h1>
      <p>{data?.user?.email}</p>
    </div>
  );
}
```

## Configuring Codegen for Your Project

### Basic codegen.ts Configuration

```typescript
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'http://localhost:8080/v1/graphql', // Your GraphQL endpoint
  documents: ['src/graphql/**/*.graphql'],
  generateLocally: true,
  hooks: { afterAllFileWrite: ['prettier --write'] },
  generates: {
    'src/generated/types.ts': {
      plugins: ['typescript'],
      config: {
        scalars: {
          uuid: 'string',
          timestamptz: 'string',
        },
      },
    },
    'src/generated/': {
      preset: 'near-operation-file',
      presetConfig: {
        extension: '.generated.ts',
        baseTypesPath: 'types.ts',
      },
      plugins: ['typescript-operations', 'typescript-react-apollo'],
    },
  },
};

export default config;
```

### Role-Based Configuration (Multiple Output Files)

For role-based separation, use multiple config files:

```
codegen.ts              # Base types
codegen.user.ts         # User operations
codegen.admin.ts        # Admin operations
codegen.public.ts       # Public operations
```

**codegen.user.ts example:**

```typescript
import type { CodegenConfig } from '@graphql-codegen/cli';
import baseConfig from './codegen';

const config: CodegenConfig = {
  ...baseConfig,
  documents: ['src/graphql/**/*.user.graphql'],
  generates: {
    'src/generated/user.ts': {
      plugins: ['typescript', 'typescript-operations', 'typescript-react-apollo'],
    },
  },
};

export default config;
```

## Best Practices

1. **Descriptive Names**: Use clear operation names (e.g., `GetUserProfile`, not `GetUser`)
2. **Role Appropriate**: Only query data the role should access
3. **Field Selection**: Only request fields you need (avoid over-fetching)
4. **Pagination**: Use limit/offset or cursor-based pagination for large datasets
5. **Error Handling**: Always handle loading and error states
6. **Type Safety**: Leverage generated TypeScript types fully
7. **Fragments**: Reuse common field selections with GraphQL fragments

## Testing GraphQL Operations

1. **Test in GraphQL