{"id":16821,"library":"gql.tada","title":"gql.tada","description":"gql.tada is a powerful and spec-compliant GraphQL document authoring library designed for TypeScript environments. Its primary function is to infer the result and variables types of GraphQL queries, mutations, and fragments directly within the TypeScript type system, eliminating the need for separate code generation steps. Currently at version 1.9.2, the library maintains an active development pace with frequent patch and minor releases, as evidenced by recent changelogs. A key differentiator is its deep integration with TypeScript, providing on-the-fly type safety, editor feedback, and auto-completion without external build steps, especially when paired with a language server like GraphQLSP. It achieves this by parsing GraphQL documents directly in TypeScript, deriving a schema from introspection and scalar configuration, and then mapping these definitions to robust result and variables types, including advanced features like fragment masks and gradual fragment unwrapping.","status":"active","version":"1.9.2","language":"javascript","source_language":"en","source_url":"https://github.com/0no-co/gql.tada","tags":["javascript","graphql","graphql typescript","graphql types","graphql typegen","graphql-js","client-side graphql","typescript"],"install":[{"cmd":"npm install gql.tada","lang":"bash","label":"npm"},{"cmd":"yarn add gql.tada","lang":"bash","label":"yarn"},{"cmd":"pnpm add gql.tada","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for type inference and overall functionality as it operates within the TypeScript type system. Declared as a peer dependency.","package":"typescript","optional":false}],"imports":[{"note":"The 'graphql' export is designed to be used as a tagged template literal for type inference within TypeScript. CommonJS 'require' cannot fully leverage this type-driven behavior.","wrong":"const graphql = require('gql.tada');","symbol":"graphql","correct":"import { graphql } from 'gql.tada';"},{"note":"Used to access the inferred types of a GraphQL fragment when processing data. 'useFragment' is a common naming convention in other GraphQL libraries but not directly exposed by gql.tada.","wrong":"import { useFragment } from 'gql.tada';","symbol":"readFragment","correct":"import { readFragment } from 'gql.tada';"},{"note":"This is a type-only import used to extract the TypeScript type from a GraphQL fragment definition, crucial for type-safe component props or function arguments that consume fragment data.","symbol":"FragmentOf","correct":"import type { FragmentOf } from 'gql.tada';"}],"quickstart":{"code":"import { graphql } from 'gql.tada';\nimport type { FragmentOf } from 'gql.tada';\n\n// Ensure you have configured gql.tada via its CLI (e.g., `npx gql-tada init` and `npx gql-tada generate`)\n// and have a 'graphql-env.d.ts' file at your project root or as specified in tsconfig.\n// This setup allows TypeScript to understand the `graphql` tagged template literal\n// and infer types from your GraphQL schema.\n\n// Define a GraphQL fragment for reusable fields\nconst userFragment = graphql(`\n  fragment UserProfile on User {\n    id\n    name\n    email\n  }\n`);\n\n// Define a GraphQL query that incorporates the fragment\nconst viewerQuery = graphql(`\n  query Viewer {\n    viewer {\n      ...UserProfile\n      status\n    }\n  }\n  ${userFragment} // Fragments must be included in the document\n`);\n\n// Infer the TypeScript type of the query result\ntype ViewerQueryResult = typeof viewerQuery;\n// Expected type: { viewer: { id: string, name: string, email: string, status: string | null } | null }\n\n// Infer the TypeScript type of the fragment\ntype UserProfileType = FragmentOf<typeof userFragment>;\n// Expected type: { id: string, name: string, email: string }\n\n// Example function to process query results with type safety\nfunction displayViewerData(data: ViewerQueryResult) {\n  if (data?.viewer) {\n    // Directly access fields, including those from the fragment\n    console.log(`Viewer ID: ${data.viewer.id}`);\n    console.log(`Viewer Name: ${data.viewer.name}`);\n    console.log(`Viewer Email: ${data.viewer.email}`);\n    console.log(`Viewer Status: ${data.viewer.status ?? 'N/A'}`);\n  } else {\n    console.log(\"No viewer data available.\");\n  }\n}\n\n// Mock data for demonstration purposes\nconst mockData: ViewerQueryResult = {\n  viewer: {\n    id: \"user-123\",\n    name: \"Alice Wonderland\",\n    email: \"alice@example.com\",\n    status: \"active\"\n  }\n};\n\ndisplayViewerData(mockData);\n\n// Example of a component prop type using a fragment\ninterface UserCardProps {\n  user: UserProfileType; // Type-safe prop based on the fragment\n}\n\nconst UserCard = ({ user }: UserCardProps) => {\n  return `<div class=\"user-card\"><h2>${user.name}</h2><p>Email: ${user.email}</p></div>`;\n};\n\n// Usage of the UserCard component\nif (mockData.viewer) {\n  const cardHtml = UserCard({ user: mockData.viewer });\n  console.log(cardHtml);\n}","lang":"typescript","description":"Demonstrates defining GraphQL fragments and queries using the `graphql` tagged template literal, inferring result and fragment types with `typeof` and `FragmentOf`, and safely accessing data."},"warnings":[{"fix":"Upgrade your project's TypeScript version to 5.0.0 or higher. Ensure your `tsconfig.json` is correctly configured for your TypeScript version.","message":"gql.tada requires TypeScript version ^5.0.0 || ^6.0.0 as a peer dependency. Using older versions of TypeScript (e.g., v4.x) will lead to compilation errors and prevent the library's core type inference functionality from working correctly.","severity":"breaking","affected_versions":"<=1.x"},{"fix":"Install `@gql.tada/cli` and run `npx gql-tada init` followed by `npx gql-tada generate` to set up and update your schema definition file. Ensure your `tsconfig.json` includes the generated `.d.ts` files.","message":"Full type inference and editor feedback in gql.tada relies on an introspected GraphQL schema being available to the TypeScript language server. This is typically achieved by using `@gql.tada/cli` to generate a `graphql-env.d.ts` file. Without this pre-generated schema environment, the `graphql` tagged template literal will not provide comprehensive type safety for your queries.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade `gql.tada` to version `1.8.13` or higher to ensure you have the fixes for external scalar handling. If using `@gql.tada/cli-utils` directly, upgrade it to `1.7.1` or higher.","message":"Prior to `@gql.tada/cli-utils@1.7.1` (which ships with `gql.tada@1.8.13` and above), there was an issue where external scalar types might not be correctly handled in the generated `graphql` definition files, leading to incorrect type inferences for custom scalars. If using custom scalars with older versions, type safety might be compromised.","severity":"gotcha","affected_versions":"<1.8.13"},{"fix":"Ensure you are using the latest stable TypeScript version (currently v5.x or v6.x). Consider optimizing your `tsconfig.json` settings, using a modern module resolution strategy like `NodeNext` or `Bundler`, and leveraging incremental builds or build caches if available in your project setup.","message":"While gql.tada is optimized for performance, very large and complex GraphQL schemas, especially when combined with older TypeScript versions or less performant build setups, can potentially lead to increased type checking times due to the intensive type system operations involved in on-the-fly inference.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure `@gql.tada/cli` is installed and run `npx gql-tada init` followed by `npx gql-tada generate`. Verify your `tsconfig.json` includes the generated `graphql-env.d.ts` file.","cause":"The `@gql.tada/codegen-env` import or the `graphql-env.d.ts` file is missing, incorrectly configured, or `@gql.tada/cli` has not generated the necessary environment types for the TypeScript language server.","error":"Module '\"gql.tada\"' has no exported member 'graphql'."},{"fix":"Check your `tsconfig.json` to ensure `graphql-env.d.ts` is included and that `moduleResolution` and `module` settings are compatible (e.g., `NodeNext` or `Bundler`). Restart your TypeScript language server or IDE to refresh type definitions.","cause":"TypeScript is not recognizing the `graphql` template literal tag as a special type-generating construct. This typically indicates that the `codegen-env` or schema types provided by `gql.tada` are not correctly loaded or interpreted by TypeScript.","error":"Type 'string' is not assignable to type 'DocumentNode<any, any>'."},{"fix":"Review the GraphQL query for typos or mismatches against your schema. If your schema has changed, run `npx gql-tada generate` to update your local schema definition file and then restart your TypeScript language server/IDE.","cause":"The GraphQL query within the `graphql` tag does not match the actual schema, or the introspected schema used by `gql.tada` for type inference is outdated or incorrect, leading to a mismatch between the query and the inferred type.","error":"Property 'someField' does not exist on type '{ /* ... */ }'."}],"ecosystem":"npm","meta_description":null}