gql.tada 🪄

Magical GraphQL query engine for TypeScript

gql.tada is a GraphQL document authoring library, inferring the result and variables types of GraphQL queries and fragments in the TypeScript type system. It derives the types for your GraphQL queries on the fly allowing you to write type-safe GraphQL documents quickly.

In short, gql.tada,

• parses your GraphQL documents in the TypeScript type system
• uses your introspected schema and scalar configuration to derive a schema
• maps your GraphQL queries and fragments with the schema to result and variables types
• creates fragment masks and enforces unwrapping fragments gradually

Since this is all done in the TypeScript type system and type checker, this all happens while you edit your GraphQL front-end code and is always accurate.

In short, with gql.tada and GraphQLSP you get on-the-fly, automatically typed GraphQL documents with full editor feedback, auto-completion, and type hints!

📃 Documentation

Check out the “Get Started” section’s Installation page in the documentation.

• Get Started
  • Introduction — everything you need to know
  • Installation — an installation guide
  • Writing GraphQL — how to write GraphQL documents
• API Reference
  • gql.tada API — gql.tada API Reference docs
  • gql.tada CLI — gql.tada CLI Reference docs
  • Config Format — Configuration Reference docs

Furthermore, all APIs and packages are self-documented using TSDocs. If you’re using a language server for TypeScript, the documentation for each API should pop up in your editor when hovering gql.tada’s code and APIs.

🔎 Let’s take a look!

💙 Sponsors

BigCommerce

WunderGraph

The Guild

BeatGig

📦 Releases

If you'd like to get involved, check out our Contributor's guide.

All new releases and updates are listed on GitHub with full changelogs. The CHANGELOG.md file further documents all the historical changes for gql.tada.

New releases are prepared using changesets, which are changelog entries added to each PR, and we have “Version Packages” PRs that once merged will release new versions of the gql.tada package. You can use @canary releases from npm if you’d like to get a preview of the merged changes.

@gql.tada/cli-utils

1.6.3

Patch Changes

• ⚠️ Fix turbo command's cache disabling override not being effective. This was a regression that meant the cached outputs would be reused during the next run of the turbo command Submitted by @kitten (See #409)
• Create target directories if they don't exist and the CLI is trying to write to them Submitted by @kitten (See #401)

1.6.2

Patch Changes

• Strip our internal @_unmask directive from fragment-definitions during persisted-operations generation Submitted by @JoviDeCroock (See #388)
• Updated dependencies (See #386)
  • @gql.tada/internal@1.0.8

1.6.1

Patch Changes

• Upgrade dependencies Submitted by @kitten (See #373)
• Updated dependencies (See #373)
  • @gql.tada/internal@1.0.7

1.6.0

Minor Changes

• Split .vue and .svelte SFC file support out into support packages. If you need Vue support, you must now install `@gql.tada/vue-supportalongsidegql.tada, and if you need Svelte support, you must now install@gql.tada/svelte-supportalongsidegql.tada` Submitted by @kitten (See #361)

Patch Changes

• Add fallback version checks to doctor command Submitted by @kitten (See #358)
• When threading, transfer error properties to thread host Submitted by @kitten (See #359)
• Add per-package readme files Submitted by @kitten (See #363)
• Updated dependencies (See #363)
  • @gql.tada/internal@1.0.6
  • @gql.tada/svelte-support@1.0.1
  • @gql.tada/vue-support@1.0.1

1.5.3

Patch Changes

• Prevent NodeNext module resolution from being used over Bundler mode, since this is almost always a mistake Submitted by @kitten (See #356)
• Support breaking changes in @vue/language-core@2.0.28 (getBasePlugins renamed to createPlugins) Submitted by @kitten (See #353)
• Bump stack trace limit to 25 when TypeScript is used, which requires a larger stack depths to debug properly Submitted by @kitten (See #355)

1.5.2

Patch Changes

• Updated dependencies (See #350)
  • @gql.tada/internal@1.0.5

1.5.1

Patch Changes

• Updated dependencies (See #340)
  • @gql.tada/internal@1.0.4

1.5.0

Minor Changes

• Disable field-usage tracking and the co-located fragment checking for vue/svelte Submitted by @JoviDeCroock (See #334)

Patch Changes

• Updated dependencies (See #334)
  • @gql.tada/internal@1.0.3

1.4.0

Minor Changes

• Add gql.tada/ts-plugin to the init and doctor command Submitted by @kitten (See #62)

Patch Changes

• ⚠️ Fix regression omitting the exit status code from the CLI. Failing commands will now correctly output exit code 1 instead of 0 again Submitted by @kitten (See #329)
• Updated dependencies (See #62)
  • @gql.tada/internal@1.0.2

1.3.10

Patch Changes

• Bump @0no-co/graphqlsp to ^1.12.8 Submitted by @kitten (See e6f8dbc)
• Updated dependencies (See #317)
  • @gql.tada/internal@1.0.1

1.3.9

Patch Changes

• ⚠️ Fix Vue not transpiling to .tsx files properly due to missing SFC plugin Submitted by @JoviDeCroock (See #305)

1.3.8

Patch Changes

• ⚠️ Fix typo on VSCode Syntax extension detection in doctor command Submitted by @kitten (See #303)

1.3.7

Patch Changes

• Support @vue/language-core@^2.0.1's updated public API Submitted by @kitten (See #301)

1.3.6

Patch Changes

• ⚠️ Fix modules not being resolved correctly when using turbo with pnpm-installed gql.tada Submitted by @kitten (See #298)

1.3.5

Patch Changes

• Updated dependencies (See #296 and #295)
  • @gql.tada/internal@1.0.0

1.3.4

Patch Changes

• Update CLI and `@gql.tada/internalto variably support graphql^15.5.0` in addition to the preferred v16, and include future support for v17 Submitted by @kitten (See #282)
• Disable output piping on GitHub CI, as it can't reliably be detected Submitted by @kitten (See #286)
• Updated dependencies (See #284 and #282)
  • @gql.tada/internal@0.4.0

1.3.3

Patch Changes

• Add missing fragment deduplication to generate persisted command's output and add document normalization, which can be disabled using the --disable-normalization argument Submitted by @kitten (See #275)

1.3.2

Patch Changes

• Updated dependencies (See #270)
  • @gql.tada/internal@0.3.3

1.3.1

Patch Changes

• Add missing default compiler options when instantiating TypeScript in check, generate persisted, and turbo commands Submitted by @kitten (See #266)
• Updated dependencies (See #268)
  • @gql.tada/internal@0.3.2

1.3.0

Minor Changes

• Add multi-schema support to the CLI (See RFC for more details.) With multi-schema support, the configuration now accepts schemas as an option to set up multiple schemas that can be instantiated with initGraphQLTada() in parallel in the same codebase Submitted by @kitten (See #261)
• Implement multi-schema support. Read more about it in the v1.6.0 Devlog post. Submitted by undefined (See https://github.com/0no-co/gql.tada/pull/261)

Patch Changes

• Upgrade to @0no-co/graphqlsp@^0.12.0 Submitted by @kitten (See #264)
• Updated dependencies (See https://github.com/0no-co/gql.tada/pull/261)
  • @gql.tada/internal@0.3.1

1.2.2

Patch Changes

• Upgrade @vue/language-core and maintain backwards-compatibility Submitted by @kitten (See #253)
• Instantiate TypeScript from project root rather than config path Submitted by @kitten (See #254)
• Updated dependencies (See #255)
  • @gql.tada/internal@0.2.4

1.2.1

Patch Changes

• Refactor internal TypeScript instantiation (affects turbo, check, and generate-persisted commands) Submitted by @kitten (See #247)
• ⚠️ Fix resolution of default lib path when libs aren't in standard location Submitted by @kitten (See #251)
• ⚠️ Fix ESM build output file to be properly loadable Submitted by @kitten (See #247)
• ⚠️ Fix log message of generate schema to correctly display schema rather than output Submitted by @JoviDeCroock (See #249)
• Updated dependencies (See #247 and #251)
  • @gql.tada/internal@0.2.3

1.2.0

Minor Changes

• Add experimental support for .svelte files for the turbo, generate-persisted, and check commands. (Note: @0no-co/graphqlsp does not yet have support for Svelte, Vue & Volar) Submitted by @kitten (See #241)
• Add support for ${configDir} to directory path configs. When used in paths in our configuration, ${configDir} will be substituted with the location of the main tsconfig.json Submitted by @kitten (See #239)

Patch Changes

• Updated dependencies (See #239)
  • @gql.tada/internal@0.2.2

1.1.1

Patch Changes

• Use the Vue SFC compiler's source-maps when looking up positions in its TypeScript file output Submitted by @JoviDeCroock (See #236)

1.1.0

Minor Changes

• Add experimental support for .vue SFC files for the turbo, generate-persisted, and check commands. (Note: @0no-co/graphqlsp does not yet have support for Vue & Volar) Submitted by @JoviDeCroock (See #232)

Patch Changes

• Add checks for VSCode extensions to doctor command. The command now outputs a warning if the GraphQL syntax plugin is missing or if the GraphQL Language service is installed and misconfigured Submitted by @kitten (See #230)

1.0.3

Patch Changes

• Add missing argument to generate-output command to force output the .ts format instead Submitted by @kitten (See #227)
• ⚠️ Fix generate-output command outputting the .d.ts format when .ts extension was specified instead Submitted by @llllvvuu (See #225)

1.0.2

Patch Changes

• Remove null cases from schema loaders, simplifying error handling in the CLI Submitted by @kitten (See #214)
• Updated dependencies (See #222 and #214)
  • @gql.tada/internal@0.2.1

1.0.1

Patch Changes

• ⚠️ Fix hash parsing in generate-persisted command Submitted by @kitten (See #212)

1.0.0

Read the full release announcement post at: https://gql-tada.0no.co/devlog/2024-04-15

Major Changes

• Add stdout-piping support in some commands and adjust command arguments for consistency Submitted by @kitten (See #197)
• Add stylised log output and threading to commands Submitted by @kitten (See #200)

Minor Changes

• Add gql-tada turbo which will calculate all the types from graphql() calls so subsequent clones, ... won't have to calculate all the types Submitted by @JoviDeCroock (See #183)
• Implement generate-persisted as a way to go through all of the codebase and generate a persisted operations manifest Submitted by @JoviDeCroock (See #176)
• Support a second argument in graphql.persisted which accepts a TadaDocumentNode rather than passing a generic. This allows the document node to not be hidden, to still generate documentId via gql.tada without having to hide the document during runtime Submitted by @JoviDeCroock (See #188)
• Expose internal generate commands as functions exported by `@gql.tada/cli-utils` (restoring prior functionality) Submitted by @kitten (See #207)
• Add check as a way to run the GraphQLSP diagnostics as part of our CLI Submitted by @JoviDeCroock (See #170)
• Add doctor command to diagnose common issues with the LSP and gql.tada Submitted by @JoviDeCroock (See #169)
• Add the init command for the CLI Submitted by @JoviDeCroock (See #182)
• Add --tsconfig option to the check command, update its log output, and add support for GitHub Actions annotations to it Submitted by @kitten (See #199)
• Add annotations for GitHub actions to command outputs that report diagnostics Submitted by @kitten (See #200)

Patch Changes

• Remove interactive output in non-interactive environments Submitted by @kitten (See #203)
• ⚠️ Fix turbo command reusing previously cached turbo typings. Instead, we now set a flag to disable the cache temporarily inside the command Submitted by @kitten (See #208)
• Add bundled licenses of internalized modules Submitted by @kitten (See #175)
• ⚠️ Fix crash in generate turbo command when returnType.symbol is undefined Submitted by @kitten (See #205)
• Improve log output of doctor command Submitted by @kitten (See #193)
• Updated dependencies (See #184, #175, #170, #192, #185, and #200)
  • @gql.tada/internal@0.2.0

0.3.3

Patch Changes

• Updated dependencies (See #172)
  • @gql.tada/internal@0.1.3

0.3.2

Patch Changes

• Update CLI with new schema loaders Submitted by @kitten (See #163)
• Update internal loader to merge them into one and incorporate SchemaOrigin parsing Submitted by @kitten (See #165)
• Updated dependencies (See #163, #168, and #165)
  • @gql.tada/internal@0.1.2

0.3.1

Patch Changes

• Add typescript to peerDependencies Submitted by @kitten (See #156)
• Updated dependencies (See #156)
  • @gql.tada/internal@0.1.1

0.3.0

Minor Changes

• Enable pre-processed introspection output by default (since it only applies to d.ts outputs) Submitted by @kitten (See #155)
• Expose introspection output format generation from `@gql.tada/internaland implement a new pre-processed output format, which pre-computes the output of themapIntrospection` type Submitted by @kitten (See #150)
• Add `@gql.tada/internal` package to extract common logic between the CLI and the LSP Submitted by @JoviDeCroock (See #149)

Patch Changes

• Updated dependencies (See #150 and #149)
  • @gql.tada/internal@0.1.0

0.2.0

Minor Changes

• Abstract core logic for generate-schema and generate-output CLI commands into importable Node.js API's Submitted by @matthewvolk (See #135)

0.1.2

Patch Changes

• ⚠️ Fix generate-schema not forwarding single header Submitted by @deini (See #131)

0.1.1

Patch Changes

• Add generate-schema command which takes a URL | path to a JSON file and outputs a graphql schema. Example: gql-tada generate-schema https://example.com ./schema.graphql --header 'authorization: bearer token' Submitted by @JoviDeCroock (See #120)

0.1.0

Minor Changes

• Add CLI entrypoint gql-tada capable of generating the types file without the LSP running Submitted by @JoviDeCroock (See #58)