Constructive GraphQL Codegen

Generate type-safe React Query hooks, Prisma-like ORM client, or inquirerer-based CLI from GraphQL schema files, endpoints, databases, or PGPM modules. Also generates documentation in multiple formats.

When to Apply

Use this skill when:

• Setting up GraphQL code generation for a PostGraphile backend
• User asks to generate hooks, ORM, CLI, or type-safe GraphQL client
• Exporting a GraphQL schema from a database or endpoint
• Generating documentation (README, AGENTS.md, skill files, MCP tool definitions)
• Implementing features that need to fetch or mutate data
• Using previously generated hooks, ORM, or CLI code
• Regenerating code after schema changes

Important: Always prefer generated code over raw GraphQL queries or SQL.

Recommended Workflow: Schema Export + Schema Directory

The recommended approach is a two-step workflow using schema export followed by schemaDir. This is the most deterministic and portable way to use codegen:

Step 1: Export schema(s) to .graphql files

Export your schema from any source (database, PGPM module, endpoint) into a directory of .graphql files:

# Export from database
npx @constructive-io/graphql-codegen --schema-only --schemas public --schema-only-output ./schemas --schema-only-filename public.graphql

# Export from PGPM module (via config)
npx @constructive-io/graphql-codegen --schema-only -c graphql-codegen.config.ts

# Export from endpoint
npx @constructive-io/graphql-codegen --schema-only -e https://api.example.com/graphql --schema-only-output ./schemas

Or programmatically:

import { generate } from '@constructive-io/graphql-codegen';

// Export from database
await generate({
  db: { schemas: ['public'] },
  schemaOnly: true,
  schemaOnlyOutput: './schemas',
  schemaOnlyFilename: 'public.graphql',
});

// Export from PGPM module
await generate({
  db: {
    pgpm: { modulePath: './packages/my-module' },
    schemas: ['app_public'],
  },
  schemaOnly: true,
  schemaOnlyOutput: './schemas',
  schemaOnlyFilename: 'app_public.graphql',
});

Step 2: Generate code from the schema directory

Point schemaDir at the directory containing your .graphql files. Each file automatically becomes a separate target:

// graphql-codegen.config.ts
import { defineConfig } from '@constructive-io/graphql-codegen';

export default defineConfig({
  schemaDir: './schemas',   // Directory of .graphql files
  output: './generated',    // Each file becomes ./generated/{name}/
  reactQuery: true,
  orm: true,
});

npx @constructive-io/graphql-codegen -c graphql-codegen.config.ts

Given schemas/public.graphql and schemas/admin.graphql, this produces:

generated/
  public/          # Generated from public.graphql
    hooks/
    orm/
  admin/           # Generated from admin.graphql
    hooks/
    orm/

Why this approach is best:

• Deterministic — .graphql files are static, version-controllable artifacts
• Portable — no live database or endpoint needed at code generation time
• Fast — no network requests or ephemeral database creation during codegen
• Reviewable — schema changes show up as clear diffs in version control

Quick Start

Installation

pnpm add @constructive-io/graphql-codegen

Generate React Query Hooks

npx @constructive-io/graphql-codegen --react-query -s ./schemas/public.graphql -o ./generated

Generate ORM Client

npx @constructive-io/graphql-codegen --orm -s ./schemas/public.graphql -o ./generated

Generate CLI

npx @constructive-io/graphql-codegen --cli -s ./schemas/public.graphql -o ./generated

Generate from Endpoint

npx @constructive-io/graphql-codegen --react-query -e https://api.example.com/graphql -o ./generated

Generate from Database

npx @constructive-io/graphql-codegen --react-query --schemas public,app_public -o ./generated

Programmatic API

Use the generate() function to integrate codegen into your build scripts or tools.

Import and Basic Usage

import { generate } from '@constructive-io/graphql-codegen';

// Generate from endpoint
await generate({
  endpoint: 'https://api.example.com/graphql',
  output: './generated',
  reactQuery: true,
  orm: true,
});

// Node.js with undici dispatcher (fixes localhost DNS issues)
await generate({
  endpoint: 'http://api.localhost:3000/graphql',
  output: './generated',
  reactQuery: true,
  browserCompatible: false,  // Use undici with custom dispatcher
});

Schema Sources

// From GraphQL endpoint
await generate({
  endpoint: 'https://api.example.com/graphql',
  headers: { Authorization: 'Bearer token' },
  reactQuery: true,
});

// From schema file
await generate({
  schemaFile: './schema.graphql',
  output: './generated',
  orm: true,
});

// From database (explicit schemas)
await generate({
  db: { schemas: ['public', 'app_public'] },
  reactQuery: true,
});

// From database (auto-discover via API names)
await generate({
  db: { apiNames: ['my_api'] },
  orm: true,
});

// From PGPM module
await generate({
  db: {
    pgpm: { modulePath: './packages/my-module' },
    schemas: ['public'],
  },
  reactQuery: true,
});

Generate Options

interface GenerateOptions {
  // Schema source (choose one)
  endpoint?: string;
  schemaFile?: string;
  schemaDir?: string;       // Directory of .graphql files — auto-expands to multi-target
  db?: {
    config?: { host, port, database, user, password };
    schemas?: string[];
    apiNames?: string[];    // Auto-discover schemas from services_public.api_schemas
    pgpm?: { modulePath, workspacePath, moduleName };
    keepDb?: boolean;       // Keep ephemeral DB after introspection (debugging)
  };
  
  // Output
  output?: string;  // Default: './generated/graphql'
  
  // Generators
  reactQuery?: boolean;  // Default: false
  orm?: boolean;         // Default: false
  cli?: CliConfig | boolean; // Default: false — generate inquirerer CLI
  
  // Schema export (instead of code generation)
  schemaOnly?: boolean;          // Export schema to .graphql file, skip codegen
  schemaOnlyOutput?: string;     // Output directory for exported schema
  schemaOnlyFilename?: string;   // Filename (default: 'schema.graphql')
  
  // Documentation (generated alongside code)
  docs?: DocsConfig | boolean; // Default: { readme: true, agents: true, mcp: false, skills: false }
  
  // Node.js HTTP adapter (auto-enabled when cli is true)
  nodeHttpAdapter?: boolean; // Default: false
  
  // Filtering
  tables?: { include?, exclude?, systemExclude? };
  queries?: { include?, exclude?, systemExclude? };
  mutations?: { include?, exclude?, systemExclude? };
  excludeFields?: string[];
  
  // Authentication
  headers?: Record<string, string>;
  authorization?: string;  // Convenience for Authorization header
  
  // Options
  verbose?: boolean;
  dryRun?: boolean;
  skipCustomOperations?: boolean;
}

Build Script Example

// scripts/codegen.ts
import { generate } from '@constructive-io/graphql-codegen';

async function main() {
  console.log('Generating GraphQL code...');
  
  const result = await generate({
    endpoint: process.env.GRAPHQL_ENDPOINT!,
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
    },
    output: './src/generated',
    reactQuery: true,
    orm: true,
    tables: {
      include: ['User', 'Post', 'Comment'],
    },
  });
  
  if (!result.success) {
    console.error('Codegen failed:', result.error);
    process.exit(1);
  }
  
  console.log('✓ Code generated successfully');
}

main();

CLI Commands

Note: The CLI does not use subcommands. All options are passed directly to graphql-codegen.

Common Options

Configuration File

Create a configuration file manually:

File: graphql-codegen.config.ts

import { defineConfig } from '@constructive-io/graphql-codegen';

// RECOMMENDED: From a directory of .graphql schema files
export default defineConfig({
  schemaDir: './schemas',
  output: './generated',
  reactQuery: true,
  orm: true,
});

// From a single schema file
export default defineConfig({
  schemaFile: './schemas/public.graphql',
  output: './generated',
  reactQuery: true,
  orm: true,
});

// From GraphQL endpoint
export default defineConfig({
  endpoint: 'https://api.example.com/graphql',
  output: './generated',
  reactQuery: true,
  orm: true,
  headers: {
    Authorization: `Bearer ${process.env.API_TOKEN}`,
  },
});

// From database
export default defineConfig({
  db: {
    schemas: ['public', 'app_public'],  // Explicit schemas
    // OR
    apiNames: ['my_api'],  // Auto-discover schemas from API
  },
  output: './generated',
  reactQuery: true,
});

// From PGPM module
export default defineConfig({
  db: {
    pgpm: { modulePath: './packages/my-module' },
    schemas: ['public'],
  },
  output: './generated',
  orm: true,
});

CLI Generation

export default defineConfig({
  endpoint: 'https://api.example.com/graphql',
  output: './generated',
  cli: true,  // Generate CLI with default tool name
  // OR with options:
  cli: {
    toolName: 'myapp',      // Config stored at ~/.myapp/
    entryPoint: true,        // Generate runnable index.ts
    builtinNames: {          // Override infra command names
      auth: 'credentials',
      context: 'env',
    },
  },
});

When cli: true, nodeHttpAdapter is auto-enabled (Node.js HTTP adapter for localhost subdomain resolution).

Documentation Generation

export default defineConfig({
  endpoint: 'https://api.example.com/graphql',
  output: './generated',
  orm: true,
  docs: true,  // Enable all doc formats
  // OR configure individually:
  docs: {
    readme: true,   // README.md — human-readable overview
    agents: true,   // AGENTS.md — structured for LLM consumption
    mcp: false,     // mcp.json — MCP tool definitions
    skills: true,   // skills/ — per-command .md skill files (Devin-compatible)
  },
});

docs.skills: Generates a skills/ directory with individual .md files for each command. Compatible with Devin and similar agent skill systems. Each skill file contains description, usage, and examples.

docs.agents: Generates an AGENTS.md with tool definitions, exact signatures, input/output schemas, workflow recipes, and machine-parseable sections.

docs.mcp: Generates an mcp.json with MCP (Model Context Protocol) tool definitions. Each CLI command becomes a tool with typed JSON Schema inputSchema.

Node.js HTTP Adapter

export default defineConfig({
  endpoint: 'http://api.localhost:3000/graphql',
  output: './generated',
  orm: true,
  nodeHttpAdapter: true,  // Generates node-fetch.ts with NodeHttpAdapter
});

The NodeHttpAdapter uses node:http/node:https for requests, enabling local development with subdomain-based routing (e.g., auth.localhost:3000). No global patching required.

import { NodeHttpAdapter } from './orm/node-fetch';
import { createClient } from './orm';

const db = createClient({
  adapter: new NodeHttpAdapter(endpoint, headers),
});

Multi-Target Configuration

There are three ways to get multi-target generation:

1. Schema directory (recommended)

schemaDir automatically creates one target per .graphql file in the directory:

export default defineConfig({
  schemaDir: './schemas',   // Contains public.graphql, admin.graphql, etc.
  output: './generated',    // Produces ./generated/public/, ./generated/admin/, etc.
  reactQuery: true,
  orm: true,
});

2. Explicit multi-target

Define each target explicitly when they have different sources or options:

export default defineConfig({
  public: {
    schemaFile: './schemas/public.graphql',
    output: './generated/public',
    reactQuery: true,
  },
  admin: {
    schemaFile: './schemas/admin.graphql',
    output: './generated/admin',
    orm: true,
    cli: true,
  },
});

3. Auto-expand from multiple API names

When db.apiNames contains multiple entries, each API name automatically becomes a separate target:

export default defineConfig({
  db: { apiNames: ['public', 'admin'] },
  output: './generated',  // Produces ./generated/public/, ./generated/admin/
  orm: true,
});

This queries services_public.api_schemas for each API name to resolve the corresponding PostgreSQL schemas, then generates each target independently.

Shared PGPM sources in multi-target

When multiple targets share the same PGPM module, the codegen automatically deduplicates ephemeral database creation. One ephemeral database is created and reused across all targets that reference the same module, avoiding redundant deploys.

Using Generated Hooks

Configure Client (once at app startup)

import { configure } from '@/generated/hooks';

configure({
  endpoint: process.env.NEXT_PUBLIC_GRAPHQL_URL!,
  headers: { Authorization: `Bearer ${getToken()}` },
});

Query Data

import { useUsersQuery } from '@/generated/hooks';

function UserList() {
  const { data, isLoading } = useUsersQuery({
    first: 10,
    filter: { role: { eq: 'ADMIN' } },
  });

  if (isLoading) return <Spinner />;
  return <ul>{data?.users?.nodes.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

Mutate Data

import { useCreateUserMutation } from '@/generated/hooks';

function CreateUser() {
  const createUser = useCreateUserMutation();

  return (
    <button onClick={() => createUser.mutate({ input: { name: 'John' } })}>
      Create
    </button>
  );
}

Using Generated CLI

When cli: true is set, codegen generates inquirerer-based CLI commands to {output}/cli/.

Generated Structure

generated/cli/
  commands/           # One file per table + custom operations
    users.ts          # CRUD commands for users table
    posts.ts          # CRUD commands for posts table
    my-query.ts       # Custom query command
  command-map.ts      # Maps command names to handlers
  executor.ts         # Command executor with auth context
  utils.ts            # Shared utilities
  node-fetch.ts       # NodeHttpAdapter for localhost
  index.ts            # Entry point (if entryPoint: true)

Running the CLI

If entryPoint: true is set:

npx ts-node generated/cli/index.ts

Or integrate the command map into your own CLI:

import { commands } from './generated/cli/command-map';
import { Inquirerer } from 'inquirerer';

const prompter = new Inquirerer();
await commands.users.list(argv, prompter);

Built-in Infrastructure Commands

The CLI includes infrastructure commands:

• auth (or credentials if name collides) — manage API credentials stored via appstash
• context (or env if name collides) — manage endpoint and auth context

Using Generated ORM

Create Client

import { createClient } from '@/generated/orm';

export const db = createClient({
  endpoint: process.env.GRAPHQL_URL!,
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
});

Query Data

const users = await db.user.findMany({
  select: { id: true, name: true, email: true },
  filter: { role: { eq: 'ADMIN' } },
  first: 10,
}).execute().unwrap();

Relations

const posts = await db.post.findMany({
  select: {
    id: true,
    title: true,
    author: { select: { id: true, name: true } },
  },
}).execute().unwrap();

// posts[0].author.name is fully typed

Error Handling

const result = await db.user.findOne({ id: '123' }).execute();

if (result.ok) {
  console.log(result.value.name);
} else {
  console.error(result.error.message);
}

// Or use helpers
const user = await db.user.findOne({ id }).execute().unwrap(); // throws on error
const user = await db.user.findOne({ id }).execute().unwrapOr(defaultUser);

Schema Sources

The codegen supports 6 schema source modes. The recommended approach is schema export + schemaDir (see top of this document).

From Schema Directory (recommended)

npx @constructive-io/graphql-codegen --react-query --orm --schema-dir ./schemas -o ./generated

From Schema File

npx @constructive-io/graphql-codegen --react-query -s ./schemas/public.graphql -o ./generated

From GraphQL Endpoint

npx @constructive-io/graphql-codegen --react-query -e https://api.example.com/graphql

From Database

# Explicit schemas
npx @constructive-io/graphql-codegen --orm --schemas public,app_public

# Auto-discover from API names
npx @constructive-io/graphql-codegen --react-query --api-names my_api

From PGPM Module

// In config file — direct path
export default defineConfig({
  db: {
    pgpm: { modulePath: './packages/my-module' },
    schemas: ['public'],
  },
  reactQuery: true,
});

// In config file — workspace + module name
export default defineConfig({
  db: {
    pgpm: {
      workspacePath: '.',
      moduleName: 'my-module',
    },
    schemas: ['app_public'],
  },
  orm: true,
});

PGPM module sources create an ephemeral database, deploy the module, introspect the schema via PostGraphile, then tear down the database (unless keepDb: true for debugging).

Schema Export

Schema export (schemaOnly: true) fetches a schema from any source and writes it as a .graphql SDL file without generating any code. This is the recommended first step in the two-step workflow.

CLI

# Export from database
npx @constructive-io/graphql-codegen --schema-only --schemas public --schema-only-output ./schemas --schema-only-filename public.graphql

# Export from endpoint
npx @constructive-io/graphql-codegen --schema-only -e https://api.example.com/graphql --schema-only-output ./schemas

# Export from PGPM module (via config)
npx @constructive-io/graphql-codegen --schema-only -c codegen.config.ts

Programmatic

import { generate } from '@constructive-io/graphql-codegen';

const result = await generate({
  db: { schemas: ['public'] },
  schemaOnly: true,
  schemaOnlyOutput: './schemas',
  schemaOnlyFilename: 'public.graphql',
});

console.log(result.message); // "Schema exported to ./schemas/public.graphql"

Options

Query Key Factory (React Query)

Generated hooks include a centralized query key factory for type-safe cache management:

import { userKeys, invalidate, remove } from '@/generated/hooks';
import { useQueryClient } from '@tanstack/react-query';

const queryClient = useQueryClient();

// Invalidate queries (triggers refetch)
invalidate.user.all(queryClient);        // All user queries
invalidate.user.lists(queryClient);      // All list queries
invalidate.user.detail(queryClient, id); // Specific user

// Remove from cache (for delete operations)
remove.user(queryClient, userId);

// Track in-flight mutations
import { userMutationKeys } from '@/generated/hooks';
import { useIsMutating } from '@tanstack/react-query';

const isMutating = useIsMutating({ mutationKey: userMutationKeys.all });

See references/query-keys.md for details.

Filter Syntax

// Comparison
filter: { age: { eq: 25 } }
filter: { age: { gte: 18, lt: 65 } }
filter: { status: { in: ['ACTIVE', 'PENDING'] } }

// String
filter: { name: { contains: 'john' } }
filter: { email: { endsWith: '.com' } }

// Logical
filter: {
  OR: [
    { role: { eq: 'ADMIN' } },
    { role: { eq: 'MODERATOR' } },
  ],
}

Troubleshooting

References

For detailed documentation on specific topics only when needed, see references/:

• CLI options and configuration: cli-reference.md, config-reference.md
• Advanced usage patterns: hooks-patterns.md, orm-patterns.md
• Error handling and relations: error-handling.md, relations.md
• Query key factory and cache management: query-keys.md
• Generated output structure: hooks-output.md, orm-output.md