@soda-gql/cli

@soda-gql - Zero-runtime GraphQL Query Generation

A zero-runtime GraphQL query generation system that brings PandaCSS's approach to GraphQL. Write type-safe queries in TypeScript that are statically analyzed and transformed at build time into optimized GraphQL documents.

Features

• 🔍 Full Type Safety: Complete TypeScript inference from schema to query results
• 🎯 No Code Generation Loop: Unlike traditional GraphQL codegen, no constant regeneration needed
• 💡 LSP Integration: VS Code extension with hover, completion, and diagnostics for tagged templates
• 🔧 Transform Functions: Built-in data normalization at the fragment level
• 📦 Modular Architecture: Compose queries from reusable fragments
• ⚡ Instant Feedback: Type errors appear immediately in your IDE

Project Structure

packages/
├── core/              # Core GraphQL types, utilities, and runtime
├── dev/               # CLI, codegen, typegen, and formatter (dev tooling)
├── builder/           # Static analysis & artifact generation
├── babel/             # Babel transformer and plugin
├── tsc/               # TypeScript transformer and plugin
├── swc/               # SWC-based native transformer
├── webpack-plugin/    # Webpack plugin with HMR support
├── vite-plugin/       # Vite plugin
├── metro-plugin/      # Metro plugin (React Native)
├── lsp/               # Language Server Protocol implementation
└── vscode-extension/  # VS Code extension for LSP

Quick Start

For Users

# Install packages
bun add @soda-gql/core
bun add -D @soda-gql/tools @soda-gql/config

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",
    },
  },
});

Generate the GraphQL system:

# Scaffold inject template with scalar and adapter definitions (first-time setup)
bun run soda-gql codegen schema --emit-inject-template ./src/graphql-system/default.inject.ts

# Generate GraphQL system from schema
bun run soda-gql codegen schema

The generated module imports your scalar definitions from the inject file. Keep the inject file (e.g., default.inject.ts) under version control so custom scalar behavior stays explicit.

LSP Integration (VS Code)

Recommended workflow: Install the VS Code extension to get real-time type information, completion, and diagnostics without running typegen.

# Install the VS Code extension
code --install-extension soda-gql-*.vsix

With the extension installed, you get: