@soda-gql/cli

Command-line interface for soda-gql zero-runtime GraphQL code generation.

Installation

bun add -D @soda-gql/cli @soda-gql/config

Usage

Configuration

Create a soda-gql.config.ts file in your project root:

import { defineConfig } from "@soda-gql/config";

export default defineConfig({
  outdir: "./src/graphql-system",
  include: ["./src/**/*.ts"],
  schemas: {
    default: {
      schema: "./schema.graphql",
      inject: "./src/graphql-system/default.inject.ts",
    },
  },
});

Commands

Generate GraphQL System

bun run soda-gql codegen schema

This command:

1. Reads your GraphQL schema
2. Generates type-safe GraphQL system module
3. Outputs to the directory specified in outdir

Scaffold Templates

For first-time setup, generate inject template with scalar and adapter definitions:

bun run soda-gql codegen schema --emit-inject-template ./src/graphql-system/default.inject.ts

Generate from .graphql Files

Convert existing .graphql operation files to soda-gql compat pattern:

bun run soda-gql codegen graphql --input "src/**/*.graphql"

This generates TypeScript files alongside input files using the compat API pattern, allowing gradual migration from traditional .graphql files.

Options:

| Option | Description | |--------|-------------| | --config <path> | Path to config file | | --schema <name> | Schema name (required if multiple schemas configured) | | --input <glob> | Glob pattern for .graphql files (repeatable) | | --suffix <ext> | Output file suffix (default: .compat.ts) |

Example:

# Generate compat files from all .graphql files in src/
bun run soda-gql codegen graphql --input "src/**/*.graphql"

# Generate with custom suffix
bun run soda-gql codegen graphql --input "src/**/*.graphql" --suffix ".generated.ts"

Generate Prebuilt Types

bun run soda-gql typegen

Analyzes your TypeScript source files and generates prebuilt type definitions for all soda-gql operations and fragments. Run this after codegen schema to get compile-time type safety.

Options:

| Option | Description | |--------|-------------| | --config <path> | Path to config file | | --watch, -w | Watch for file changes and regenerate automatically |

Watch mode (--watch / -w) monitors your source files for changes and regenerates types automatically. It uses 150ms debounce to batch rapid changes, automatic rebuilds on each change, and automatic error recovery — a failed build does not stop the watcher.

# One-time generation
bun run soda-gql typegen

# Watch mode for development
bun run soda-gql typegen --watch

Note: Schema codegen always generates a CommonJS bundle (.cjs) alongside TypeScript source files for runtime module loading. No --bundle flag is needed.

CLI Options

| Option | Description | |--------|-------------| | --config <path> | Path to config file (auto-discovered if not specified) | | --emit-inject-template <path> | Generate scaffold template for scalars and adapter definitions | | --format <type> | Output format: human (default) or json |

Config File Discovery

The CLI automatically searches for configuration files in the following order:

1. soda-gql.config.ts
2. soda-gql.config.mts
3. soda-gql.config.js
4. soda-gql.config.mjs

Example Workflow

# 1. Install dependencies
bun add @soda-gql/core @soda-gql/runtime
bun add -D @soda-gql/cli @soda-gql/config

# 2. Create config file
cat > soda-gql.config.ts << 'EOF'
import { defineConfig } from "@soda-gql/config";

export default defineConfig({
  outdir: "./src/graphql-system",
  include: ["./src/**/*.ts"],
  schemas: {
    default: {
      schema: "./schema.graphql",
      inject: "./src/graphql-system/default.inject.ts",
    },
  },
});
EOF

# 3. Generate templates (first-time only)
bun run soda-gql codegen schema --emit-inject-template ./src/graphql-system/default.inject.ts

# 4. Generate GraphQL system
bun run soda-gql codegen schema

Related Packages

• @soda-gql/config - Configuration management
• @soda-gql/codegen - Code generation engine
• @soda-gql/core - Core types and utilities

License

MIT