#What is soda-gql?

soda-gql is a zero-runtime-like 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.

#Why soda-gql?

Traditional GraphQL development involves a code generation loop:

1. Write GraphQL queries
2. Run codegen to generate TypeScript types
3. Import and use the generated types
4. Repeat for every change

This cycle creates friction: you write code in two languages, wait for generation, and deal with out-of-sync types.

soda-gql eliminates this loop. You write everything in TypeScript, and the build system handles the rest.

#What "Zero-Runtime-Like" Means

Inspired by PandaCSS, soda-gql analyzes your code at build time and embeds pre-computed data as JSON. However, unlike CSS which is truly zero-runtime, soda-gql still requires runtime processing for:

• Query execution against GraphQL servers
• Response parsing and type coercion
• Variable interpolation

What happens at build time:

• GraphQL document string generation
• Metadata computation
• Type validation

This approach eliminates the codegen loop while keeping runtime overhead minimal.

#Core Concepts

#Fragments

Fragments define reusable field selections for GraphQL types using tagged template syntax:

import { gql } from "@/graphql-system";

export const userFragment = gql.default(({ fragment }) =>
  fragment("UserFragment", "User")`{
    id
    name
    email
  }`(),
);

#Operations

Operations define complete GraphQL queries, mutations, or subscriptions with field selections:

export const profileQuery = gql.default(({ query }) =>
  query("ProfileQuery")`($userId: ID!) {
    user(id: $userId) {
      ...${userFragment}
    }
  }`(),
);

#Next Steps

Ready to get started? Head to the Getting Started guide.