graphql-codegen skill
Generates typed operations, hooks, and document nodes from GraphQL schemas for type-safe frontend development.
- GitHub stars
- 47
- Files
- 4
- Last commit
- Nov 9, 2026
- License
- MIT
- Allowed tools
- 6
What does the graphql-codegen skill do?
graphql-codegen generates typed operations, hooks, and document nodes from GraphQL schemas for type-safe frontend development.
Summary generated from the skill's SKILL.md.
About the graphql-codegen skill
Frontend developers can automate the creation of TypeScript types and hooks by using this tool to transform GraphQL schemas into usable code. It is designed for projects requiring type-safe GraphQL clients, specifically when working with React or TanStack Query. An agent should load this skill when a user needs to generate typed operations, implement fragment masking, or set up a client preset for modern frontend development.
The tool produces typed document nodes, hooks, and operations based on provided schema URLs or local files and existing document paths. It relies on bash commands and file system tools like Read, Write, and Edit to manage configuration files and execute the generation process. Unlike other tools, it focuses specifically on GraphQL code generation rather than REST APIs or schema design, providing specialized plugins for React Query integration and fragment colocation.
What an agent can do with it
- 1Generate TypeScript types from schemaCreate a type-safe GraphQL client by generating operations and hooks from a schema URL.
- 2Automate type updates during developmentRun the generator in watch mode to automatically update TypeScript definitions whenever schema or document files change.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the graphql-codegen skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the graphql-codegen skill in Claude Code
~/.claude/skills/graphql-codegen/SKILL.md
$ npx degit claude-dev-suite/claude-dev-suite/skills/api-integration/graphql-codegen ~/.claude/skills/graphql-codegenInstall the graphql-codegen skill in Claude Code (project)
.claude/skills/graphql-codegen/SKILL.md
$ npx degit claude-dev-suite/claude-dev-suite/skills/api-integration/graphql-codegen .claude/skills/graphql-codegenInstall the graphql-codegen skill in Codex
~/.agents/skills/graphql-codegen/SKILL.md
$ npx degit claude-dev-suite/claude-dev-suite/skills/api-integration/graphql-codegen ~/.agents/skills/graphql-codegenInstall the graphql-codegen skill in Gemini CLI
~/.gemini/skills/graphql-codegen/SKILL.md
$ npx degit claude-dev-suite/claude-dev-suite/skills/api-integration/graphql-codegen ~/.gemini/skills/graphql-codegenInstall the graphql-codegen skill in Claude.ai
npx degit claude-dev-suite/claude-dev-suite/skills/api-integration/graphql-codegen graphql-codegen && zip -r graphql-codegen.zip graphql-codegen # claude.ai → Customize → Skills → + → Create skill → Upload a skill → graphql-codegen.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableclaude-dev-suite/claude-dev-suite/skills/api-integration/graphql-codegen is public and reachablegithub.com/claude-dev-suite/claude-dev-suite/tree/HEAD/skill ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/claude-dev-suite/claude-dev-suite/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/claude-dev-suite/claude-dev-suite/blob/HEAD/skill ↗Pass
- Pre-approved tools are scopedBash lets the agent run any shell command without askinggithub.com/claude-dev-suite/claude-dev-suite/blob/HEAD/skill ↗Finding
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 350 linesgithub.com/claude-dev-suite/claude-dev-suite/blob/HEAD/skill ↗Pass
SKILL.md
View on GitHubGraphQL Code Generator Core Knowledge
Deep Knowledge: Use
mcp__documentation__fetch_docswith technology:graphql-codegenfor comprehensive documentation.
Installation
npm install -D @graphql-codegen/cli @graphql-codegen/typescript \
@graphql-codegen/typescript-operations @graphql-codegen/client-preset
Basic Configuration
// codegen.ts
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
schema: 'http://localhost:4000/graphql',
documents: ['src/**/*.tsx', 'src/**/*.ts'],
ignoreNoDocuments: true,
generates: {
'./src/gql/': {
preset: 'client',
config: {
documentMode: 'string',
},
},
},
};
export default config;
Run Generation
npx graphql-codegen
npx graphql-codegen --watch # Watch mode
Client Preset (Recommended)
The client preset generates everything needed for type-safe GraphQL.
// codegen.ts
const config: CodegenConfig = {
schema: 'http://localhost:4000/graphql',
documents: ['src/**/*.tsx'],
generates: {
'./src/gql/': {
preset: 'client',
plugins: [],
presetConfig: {
gqlTagName: 'gql',
fragmentMasking: { unmaskFunctionName: 'getFragmentData' },
},
},
},
};
Usage
import { gql } from '../gql';
import { useQuery } from '@apollo/client';
const GET_USER = gql(`
query GetUser($id: ID!) {
user(id: $id) {
id
name
email
}
}
`);
function UserProfile({ id }: { id: string }) {
const { data, loading } = useQuery(GET_USER, {
variables: { id },
});
if (loading) return <Spinner />;
// data.user is fully typed
return <div>{data?.user?.name}</div>;
}
TanStack Query Integration
npm install -D @graphql-codegen/typescript-react-query
// codegen.ts
const config: CodegenConfig = {
schema: 'http://localhost:4000/graphql',
documents: ['src/**/*.graphql'],
generates: {
'./src/gql/index.ts': {
plugins: [
'typescript',
'typescript-operations',
'typescript-react-query',
],
config: {
fetcher: {
func: './fetcher#fetcher',
isReactHook: false,
},
reactQueryVersion: 5,
addInfiniteQuery: true,
},
},
},
};
Fetcher
// src/gql/fetcher.ts
export const fetcher = <TData, TVariables>(
query: string,
variables?: TVariables
): (() => Promise<TData>) => {
return async () => {
const response = await fetch('http://localhost:4000/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${getToken()}`,
},
body: JSON.stringify({ query, variables }),
});
const json = await response.json();
if (json.errors) {
throw new Error(json.errors[0].message);
}
return json.data;
};
};
Generated Hooks Usage
import { useGetUserQuery, useCreateUserMutation } from './gql';
function UserProfile({ id }: { id: string }) {
const { data, isLoading } = useGetUserQuery({ id });
const createMutation = useCreateUserMutation();
const handleCreate = () => {
createMutation.mutate({
input: { name: 'John', email: 'john@example.com' },
});
};
if (isLoading) return <Spinner />;
return <div>{data?.user?.name}</div>;
}
Fragment Colocation
// components/UserAvatar.tsx
import { gql, FragmentType, getFragmentData } from '../gql';
export const USER_AVATAR_FRAGMENT = gql(`
fragment UserAvatar on User {
id
name
avatarUrl
}
`);
interface Props {
user: FragmentType<typeof USER_AVATAR_FRAGMENT>;
}
export function UserAvatar({ user }: Props) {
const data = getFragmentData(USER_AVATAR_FRAGMENT, user);
return <img src={data.avatarUrl} alt={data.name} />;
}
// Usage in parent query
const GET_USER = gql(`
query GetUser($id: ID!) {
user(id: $id) {
id
...UserAvatar
}
}
`);
Production Readiness
Schema Polling
// codegen.ts
const config: CodegenConfig = {
schema: [
{
'http://localhost:4000/graphql': {
headers: {
Authorization: `Bearer ${process.env.GRAPHQL_TOKEN}`,
},
},
},
],
// ...
};
Multiple Schemas
const config: CodegenConfig = {
generates: {
'./src/gql/user-api/': {
schema: 'http://user-api:4000/graphql',
documents: ['src/features/user/**/*.tsx'],
preset: 'client',
},
'./src/gql/product-api/': {
schema: 'http://product-api:4001/graphql',
documents: ['src/features/product/**/*.tsx'],
preset: 'client',
},
},
};
CI/CD Integration
# .github/workflows/codegen.yml
name: GraphQL Codegen
on:
push:
paths:
- 'src/**/*.graphql'
- 'src/**/*.tsx'
jobs:
generate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npx graphql-codegen
- name: Check for changes
run: |
if [[ -n $(git status --porcelain src/gql) ]]; then
echo "Generated files changed"
exit 1
fi
Package Scripts
{
"scripts": {
"codegen": "graphql-codegen",
"codegen:watch": "graphql-codegen --watch"
}
}
Checklist
- Schema source configured (URL or local)
- Documents path matches source files
- Client preset for optimal output
- Fetcher configured with auth
- Fragment colocation pattern
- Watch mode for development
- CI validation of generated code
- TypeScript strict mode compatible
When NOT to Use This Skill
- REST API type generation (use
openapi-codegenskill) - tRPC type-safe APIs (use
trpcskill) - GraphQL schema design (use
graphqlskill) - Non-TypeScript projects
- Simple GraphQL queries without type generation needs
Anti-Patterns
| Anti-Pattern | Why It's Bad | Solution |
|---|---|---|
| Committing generated files to git | Merge conflicts, outdated types | Add to .gitignore, generate in CI |
| Not using client preset | Verbose configuration | Use client preset for modern setup |
| Ignoring schema changes | Type mismatches at runtime | Run codegen in watch mode during dev |
| Missing operationId or query names | Poor generated hook names | Name all queries/mutations |
| Not using fragments | Code duplication | Use fragments for reusable fields |
| Generating types only | Missing runtime validation | Combine with schema validation |
| Hardcoding schema URL | Environment coupling | Use env variables for schema source |
| Not versioning generator packages | Inconsistent output across team | Pin generator versions |
Quick Troubleshooting
| Issue | Possible Cause | Solution |
|---|---|---|
| Generation fails | Invalid schema or documents | Validate schema, check GraphQL syntax |
| Type errors after generation | Schema/code mismatch | Regenerate types, check schema changes |
| Missing types | Documents path not matching files | Check documents glob pattern |
| Duplicate operation names | Same query name in multiple files | Use unique operation names |
| Fragment not found | Fragment not in documents | Include fragment file in documents |
| Hook not generated | Not using React Query plugin | Add typescript-react-query plugin |
| "Cannot find module './gql'" | Generation didn't run | Run npm run codegen |
| Slow generation | Too many documents | Optimize glob patterns, use ignoreNoDocuments |
| Type inference not working | Wrong import path | Import from generated gql folder |
Reference Documentation
Files in this skill
4graphql-codegen skill questions
How do I install the graphql-codegen skill in Claude Code?
Run npx degit claude-dev-suite/claude-dev-suite/skills/api-integration/graphql-codegen ~/.claude/skills/graphql-codegen. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the graphql-codegen skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I run the code generation?
You can run the generator using 'npx graphql-codegen' or use 'npx graphql-codegen --watch' to enable watch mode.
Can I integrate this with TanStack Query?
Yes, you can integrate it by installing the @graphql-codegen/typescript-react-query plugin and configuring it in your codegen.ts file.
What should I do if I encounter type errors after generation?
Type errors after generation are often caused by a mismatch between the schema and your code; you should regenerate the types and check for schema changes.