Future Setup Instructions 2024/06/26 ​
TypeScript 5.5 was released recently which allows us to make an exciting quality of life change to gql.tada!
Starting from v1.8.0, as long as you're using TypeScript 5.5, you won't have to install @0no-co/graphqlsp yourself anymore, and gql.tada's setup comes down to just installing gql.tada itself. We'll be updating our documentation in the future to reflect this.
The gql.tada/ts-plugin entry ​
The only dependency you'll now need to install directly is gql.tada, so you can upgrade it and remove @0no-co/graphqlsp. The gql.tada package will now install it as a sub-dependency.
npm uninstall --save-dev @0no-co/graphqlsp
npm install gql.tada@^1.8.0pnpm remove @0no-co/graphqlsp
pnpm add gql.tada@^1.8.0yarn remove @0no-co/graphqlsp
yarn add gql.tada@^1.8.0bun remove @0no-co/graphqlsp
bun add gql.tada@^1.8.0When you're installing from scratch
When you're setting up and installing gql.tada from scratch, this means you'll only have to install a single package.
npm install gql.tadapnpm add gql.tadayarn add gql.tadabun add gql.tadaYou can then update your tsconfig.json to use "gql.tada/ts-plugin" instead of @0no-co/graphqlsp.
{
"compilerOptions": {
"strict": true,
"plugins": [
{
"name": "@0no-co/graphqlsp",
"name": "gql.tada/ts-plugin",
"schema": "./schema.graphql",
"tadaOutputLocation": "./src/graphql-env.d.ts"
}
]
}
}Why we made this change ​
In the previous state, TypeScript before its 5.5 update only allowed full package specifiers to be used as plugins. This, and other defaults, such as VSCode not using the workspace version of TypeScript out of the box, causes situations that create friction when someone first tries out gql.tada.
However, we want gql.tada to provide you a completely frictionless experience.
We kicked off a small change request in TypeScript to allow sub-modules when specifying plugins, which now allows us to bundle gql.tada/ts-plugin as the main entrypoint to our TypeScript plugin.
What this means for our documentation ​
We're aware that when we're explaining certain concepts about how gql.tada works, our mental model of it can sometimes diverge wildly from how some of our users think about it.
As a recap, gql.tada consumes a typings file that contains a representation of your GraphQL schema. This file is generated either by the gql.tada CLI or by the TypeScript plugin, when you open a configured project. The gql.tada library's types then allow it to parse and process GraphQL documents and use the generated typings to derive GraphQL result and variables types for you.
The TypeScript plugin is often a misunderstood part of our pipeline. It's there to provide the interactive GraphQL features to the TypeScript language server, such as auto-completion, type hints, and diagnostics. But because it's a separate package, this distinction often leads to convoluted explanations in our documentation.
Since the plugin is now installed via the gql.tada/ts-plugin entrypoint, we're deemphasizing that it's separate and will update the documentation for clarity accordingly.
@defer support ​
We'd like to take this opportunity to again point out that gql.tada already has support to derive the correct types for @defer-ed fragments!
As long as your GraphQL API and client support @defer, it allows you to split up your GraphQL query to receive several parts of its result later on. It's a quick way to specify which parts of your query can be streamed in later on.
Thanks to members of The Guild testing this more extensively, we found that in certain cases using @defer (or @include and @skip) on fragments with gql.tada could cause type recursion errors.
In this latest version we patched this, and we want to encourage more people to test out @defer and see if it benefits their applications.