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:

❌ NEVER edit files in */generated/ directories - These are auto-generated
✅ ALWAYS follow .{role}.graphql naming convention - One file per role
✅ ALWAYS run codegen after GraphQL changes - Regenerate types
✅ ALWAYS verify GraphQL backend is running before codegen - Services must be available
✅ 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

# 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

# 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

# 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:

# 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

// 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

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

Mutation Template

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

Subscription Template

# 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

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

Step 2: Use in Component

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

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:

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

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

Testing GraphQL Operations

Test in GraphQL Playground/Console - Your GraphQL endpoint's UI
Test with Mock Data - Use MSW or similar for unit tests
Test Permissions - Verify role-based access works correctly
Test Error Cases - Handle network failures, validation errors

Performance Optimization

Fragments: Reuse common field selections
Batching: Combine related queries when possible
Caching: Leverage your GraphQL client's cache (Apollo, urql, etc.)
Subscriptions: Use sparingly; prefer queries with polling for most cases

Quick Reference

Task	Command
Generate all types	`pnpm codegen`
Generate specific role	`pnpm codegen:{role}`
Check GraphQL endpoint	`curl {YOUR_GRAPHQL_ENDPOINT}`
Clean and rebuild	`rm -rf generated/ && pnpm codegen`

This skill is framework and backend agnostic. Works with:

Backends: Hasura, Apollo Server, GraphQL Yoga, PostGraphile, etc.
Frameworks: React, Next.js, Vue, Svelte, Solid, etc.
Clients: Apollo Client, urql, GraphQL Request, etc.

graphql-workflow