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.0
pnpm remove @0no-co/graphqlsp
pnpm add gql.tada@^1.8.l0
yarn remove @0no-co/graphqlsp
yarn add gql.tada@^1.8.0
bun remove @0no-co/graphqlsp
bun add gql.tada@^1.8.0
When 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.tada
pnpm add gql.tada
yarn add gql.tada
bun add gql.tada
You 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.