gql.tada

gql.tada is a tool designed to bridge the gap between GraphQL and TypeScript. It improves the developer experience by providing:

• Automatic Type Inference: GraphQL queries written in pure TypeScript automatically infer their types.
• Editor Feedback: Immediate auto-completion, diagnostics, and GraphQL type hints directly within your editor.
• Low Friction: Minimal setup required to get on-the-fly TypeScript support for GraphQL queries.

gql.tada is a GraphQL document authoring library designed for TypeScript. It allows you to write type-safe GraphQL queries and fragments by inferring their result and variable types directly within the TypeScript type system.

Key features include:

• Parsing GraphQL documents within the TypeScript type system.
• Deriving a schema from your introspected schema and scalar configuration.
• Mapping queries and fragments to their corresponding result and variables types.
• Creating fragment masks and enforcing gradual fragment unwrapping.

When used with GraphQLSP, it provides real-time editor feedback, auto-completion, and type hints while you edit your GraphQL code.

@gql.tada/vue-support is a support package designed for the gql.tada CLI (via @gql.tada/cli-utils). It provides transform helpers that allow the CLI to parse and process .vue Single File Components (SFCs).

Warning: This package is intended to be consumed by @gql.tada/cli-utils. Its exported API is only considered stable within that specific context and should be used at your own risk if used independently.

If you are setting up a new project with gql.tada, you only need to install the main gql.tada package. The TypeScript plugin is included automatically as a sub-dependency.

npm install gql.tada
pnpm add gql.tada
yarn add gql.tada
bun add gql.tada

When using multiple schemas, you cannot rely on the default automatic initialization. You must manually call initGraphQLTada() for each schema. This involves creating a separate file for each schema's environment, importing the specific introspection type generated for that schema, and exporting a unique graphql function.

import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './graphql/graphql-env.d.ts';

export const graphql = initGraphQLTada<{
  introspection: introspection;
}>();

export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
export { readFragment } from 'gql.tada';

If your project uses multiple GraphQL schemas, define them using a schemas array within the gql.tada/ts-plugin configuration. Each schema object requires a name (used for internal identification and error messages), a schema path/URL, and a tadaOutputLocation.

{
  "compilerOptions": {
    "strict": true,
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schemas": [
          {
            "name": "your-schema-1",
            "schema": "./schema-1.graphql",
            "tadaOutputLocation": "./src/graphql-env-1.d.ts"
          },
          {
            "name": "your-schema-2",
            "schema": "./schema-2.graphql",
            "tadaOutputLocation": "./src/graphql-env-2.d.ts"
          }
        ]
      }
    ]
  }
}

To use a fragment within a query or another fragment, you must pass the fragment into a tuple array as the second argument to the graphql() function.

import { graphql } from 'gql.tada';

const PokemonFragment = graphql(`
  fragment Pokemon on Pokemon {
    id
    name
    collected
  }
`);

const PokemonsList = graphql(`
  query PokemonsList {
    pokemons(limit: 10) {
      id
      ...Pokemon
    }
  }
`, [PokemonFragment]);

To ensure the gql.tada/ts-plugin loads correctly in VSCode, you must instruct VSCode to use the workspace's TypeScript installation rather than a global one. Create a .vscode/settings.json file with the following configuration:

{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Since gql.tada turbo is optional, you can integrate it into your workflow to speed up CI or local checks without slowing down your real-time editing experience. Recommended integration points include:

• Running it before submitting a Pull Request.
• Running it before committing changes.
• Using it as a pre-commit hook.