graphql-workflow

name	graphql-workflow
description	Activate when creating, modifying, troubleshooting, or managing GraphQL operations with codegen. This includes scaffolding .graphql files, running code generation, validating naming conventions, fixing codegen errors, or updating GraphQL types and hooks.
updated	"2025-01-13T00:00:00.000Z"

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

# 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

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 Playground/Console - Your GraphQL endpoint's UI
2. Test with Mock Data - Use MSW or similar for unit tests
3. Test Permissions - Verify role-based access works correctly
4. 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.