Menu
GraphQL code generation — typed operations, fragment colocation, and schema-first development.
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/InugamiDev/ultrathink-oss --skill graphql-codegenThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Unified design foundations — design system architecture, tokens, component specs, visual principles, creative vision, figma integration, plus brand design system loader (66 real brands via DESIGN.md). Absorbs design, design-system, design-systems, design-principles, design-router, creative-vision, figma, design-md.
Render, summarize, and present markdown documents and structured content in multiple output modes
Ultra UI skill - combines Google's DESIGN.md spec (machine-readable design tokens) with the ui-ux-pro-max knowledge base (91 styles, 161 palettes, 73 font pairings, 161 products, 104 UX guidelines, 25 chart types). Generates lint-clean DESIGN.md files, validates token references and WCAG contrast, exports Tailwind/DTCG tokens, and diffs design systems version-over-version.
Based on SOC occupation classification
| name | graphql-codegen |
| description | GraphQL code generation — typed operations, fragment colocation, and schema-first development. |
| layer | domain |
| category | tooling |
| triggers | ["graphql codegen","codegen","typed graphql","fragment colocation","gql.tada"] |
| inputs | ["GraphQL schema or operation definitions","Code generation configuration needs","Type-safe query/mutation patterns","Fragment colocation strategy questions"] |
| outputs | ["GraphQL codegen configuration files","Typed operations and fragment definitions","Custom scalar type mappings","Client-side cache integration patterns"] |
| linksTo | ["graphql","typescript-patterns"] |
| linkedFrom | [] |
| riskLevel | low |
| memoryReadPolicy | selective |
| memoryWritePolicy | none |
| sideEffects | [] |
Provide expert guidance on GraphQL code generation for type-safe client operations, fragment colocation, schema-first development, and integration with TypeScript. Covers GraphQL Codegen, gql.tada, and typed-document-node approaches.
codegen.ts configuration:
import type { CodegenConfig } from "@graphql-codegen/cli";
const config: CodegenConfig = {
schema: process.env.GRAPHQL_SCHEMA_URL || "./schema.graphql",
documents: ["src/**/*.{ts,tsx}", "!src/gql/**/*"],
ignoreNoDocuments: true,
generates: {
"./src/gql/": {
preset: "client",
presetConfig: {
fragmentMasking: { unmaskFunctionName: "getFragmentData" },
},
config: {
scalars: {
DateTime: "string",
UUID: "string",
JSON: "Record<string, unknown>",
Decimal: "string",
},
enumsAsTypes: true,
skipTypename: false,
dedupeFragments: true,
nonOptionalTypename: ,
},
},
: {
: [],
: {
: ,
: ,
},
},
},
: {
: [],
},
};
config;
package.json scripts:
{
"scripts": {
"codegen": "graphql-codegen --config codegen.ts",
"codegen:watch": "graphql-codegen --config codegen.ts --watch"
}
}
Colocate fragments with the components that use them:
// components/UserCard.tsx
import { graphql, type FragmentType, getFragmentData } from "@/gql";
export const UserCardFragment = graphql(`
fragment UserCard on User {
id
name
email
avatarUrl
role
createdAt
}
`);
interface UserCardProps {
user: FragmentType<typeof UserCardFragment>;
}
export function UserCard({ user: userRef }: UserCardProps) {
const user = getFragmentData(UserCardFragment, userRef);
return (
<div className="p-6 rounded-xl shadow-sm border">
<img
src={user.avatarUrl}
alt={user.name}
className="w-12 h-12 rounded-full"
/>
<h3 className="text-lg font-semibold">{user.name}</h3>
<p className="text-sm text-gray-600">{user.email}</p>
</div>
);
}
Parent component composes fragments:
// pages/TeamPage.tsx
import { graphql } from "@/gql";
import { useQuery } from "@urql/react";
import { UserCard, UserCardFragment } from "@/components/UserCard";
const TeamQuery = graphql(`
query TeamMembers($teamId: ID!) {
team(id: $teamId) {
id
name
members {
...UserCard
}
}
}
`);
export function TeamPage({ teamId }: { teamId: string }) {
const [{ data, fetching }] = useQuery({
query: TeamQuery,
variables: { teamId },
});
if (fetching) return <Spinner />;
return (
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
{data?.team?.members.map((member) => (
<UserCard key={member.id} user={member} />
))}
</div>
);
}
Query with variables and error handling:
import { graphql } from "@/gql";
import { useQuery } from "@urql/react";
const OrdersQuery = graphql(`
query Orders($filters: OrderFiltersInput!, $pagination: PaginationInput!) {
orders(filters: $filters, pagination: $pagination) {
edges {
node {
id
status
totalFormatted
createdAt
items {
id
product {
name
}
quantity
}
}
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
`);
export function useOrders(filters: OrderFiltersInput, cursor?: string) {
return useQuery({
query: OrdersQuery,
variables: {
filters,
pagination: { first: 20, after: cursor },
},
});
}
Mutation with optimistic update:
import { graphql } from "@/gql";
import { useMutation } from "@urql/react";
const UpdateOrderStatusMutation = graphql(`
mutation UpdateOrderStatus($input: UpdateOrderStatusInput!) {
updateOrderStatus(input: $input) {
order {
id
status
updatedAt
}
errors {
field
message
}
}
}
`);
export function useUpdateOrderStatus() {
const [result, executeMutation] = useMutation(UpdateOrderStatusMutation);
const updateStatus = async (orderId: string, status: OrderStatus) => {
const { data, error } = await executeMutation({
input: { orderId, status },
});
if (error) throw error;
if (data?.updateOrderStatus.errors?.length) {
throw new Error(data.updateOrderStatus.errors[0].message);
}
return data!.updateOrderStatus.order;
};
return { updateStatus, loading: result.fetching };
}
For projects preferring runtime inference over code generation:
// utils/graphql.ts
import { initGraphQLTada } from "gql.tada";
import type { introspection } from "@/graphql-env";
export const graphql = initGraphQLTada<{
introspection: introspection;
scalars: {
DateTime: string;
UUID: string;
JSON: Record<string, unknown>;
};
}>();
export type { FragmentOf, ResultOf, VariablesOf } from "gql.tada";
export { readFragment } from "gql.tada";
// No codegen step needed — types inferred at write-time
import { graphql, readFragment, type FragmentOf } from "@/utils/graphql";
const UserFragment = graphql(`
fragment UserFields on User {
id
name
email
}
`);
// TypeScript knows the shape automatically
type User = FragmentOf<typeof UserFragment>;
// codegen.ts scalar config
config: {
scalars: {
DateTime: {
input: "string", // what the server accepts
output: "string", // what the server returns
},
Money: {
input: "{ amount: number; currency: string }",
output: "{ amount: number; currency: string }",
},
Upload: "File",
Void: "void",
},
}
// codegen.ts — generate persisted query hashes
generates: {
"./src/gql/": {
preset: "client",
presetConfig: {
persistedDocuments: true, // generates documentId for each operation
},
},
"./persisted-documents.json": {
plugins: ["persisted-operations"],
},
}
// Client setup with automatic persisted queries
import { createClient, fetchExchange } from "@urql/core";
import { persistedExchange } from "@urql/exchange-persisted";
const client = createClient({
url: "/graphql",
exchanges: [
persistedExchange({
preferGetForPersistedQueries: true,
enforcePersistedQueries: true,
}),
fetchExchange,
],
});
// test/helpers/graphql.ts — type-safe mock factories
import type { OrdersQuery } from "@/gql/graphql";
type OrderNode = NonNullable<
OrdersQuery["orders"]
>["edges"][number]["node"];
export function buildMockOrder(overrides: Partial<OrderNode> = {}): OrderNode {
return {
__typename: "Order",
id: "order-1",
status: "PENDING",
totalFormatted: "$99.00",
createdAt: new Date().toISOString(),
items: [],
...overrides,
};
}
client preset — It generates a single graphql() function with fragment masking, simplifying imports.any types in generated output.graphql-codegen to your CI pipeline and fail on type errors.enumsAsTypes over TypeScript enums — String union types are more ergonomic than TS enums.dedupeFragments to avoid duplicate fragment definitions in operations.codegen:watch alongside your dev server for instant type updates.| Pitfall | Problem | Fix |
|---|---|---|
| Stale generated types | Types out of sync with schema | Run codegen in CI, use watch mode locally |
| Missing scalar mappings | Custom scalars typed as any | Configure all custom scalars in codegen config |
| No fragment colocation | Monolithic queries that over-fetch | Split into component-level fragments |
| Importing from wrong path | Using raw gql tag instead of generated | Always import graphql from @/gql |
| Fragment name collisions | Two fragments with the same name | Prefix fragments with component name: UserCard not User |
| Ignoring fragment masking | Accessing fields not in the component's fragment | Use getFragmentData() to unmask properly |
| No persisted queries | Arbitrary queries accepted by server | Enable persisted documents and enforce on server |
| Circular fragment deps | Codegen fails on circular references | Restructure fragments to avoid cycles |