From 6815dbb08235ae00e28fd26132f1d407fd074545 Mon Sep 17 00:00:00 2001 From: Phil Pluckthun Date: Thu, 18 Jan 2024 21:58:06 +0000 Subject: [PATCH] docs: Prefer instructions that only create .d.ts file (#27) --- .../content/docs/get-started/installation.mdx | 47 +++++++------------ .../content/docs/reference/gql-tada-api.mdx | 8 ++-- .../docs/reference/graphqlsp-config.mdx | 31 +++++++++--- 3 files changed, 46 insertions(+), 40 deletions(-) diff --git a/website/src/content/docs/get-started/installation.mdx b/website/src/content/docs/get-started/installation.mdx index d815a9a4..dddd6b15 100644 --- a/website/src/content/docs/get-started/installation.mdx +++ b/website/src/content/docs/get-started/installation.mdx @@ -9,6 +9,10 @@ The `gql.tada` package provides typings and the runtime API as a library, while `@0no-co/graphqlsp` integrates with the TypeScript language server to integrate with an IDE or editor. +On this page, we’ll go through the steps to get everything set up properly. +A quick demo of what this looks like can be found [in an example project in the `gql.tada` +repository.](https://github.com/0no-co/gql.tada/blob/main/examples/example-pokemon-api/) + ## Step 1 — Installing packages We’ll start by installing `gql.tada` as a dependency, and `@0no-co/graphqlsp` as @@ -249,39 +253,20 @@ and is **ready to be used.** Above, we let `@0no-co/graphqlsp` generate a `src/graphql-env.d.ts` file, which sets `gql.tada` up project-wide for us. -This limits what we can do, since we can’t customize any scalars, or further configuration +This allows us to import `graphql()` from `gql.tada` directly, but it limits what we +can do, since we can’t customize any scalars, or further configuration for `gql.tada`. This setup also fails if we have multiple schemas (for example, in a monorepo), since the declaration in `graphql-env.d.ts` sets a schema up project-wide. -To work around this, we may update `@0no-co/graphqlsp`’s configuration to instead -output a `.ts` file: +To work around this, we’ll create a file that uses the introspection data manually with the +`initGraphQLTada()` function to create our own `graphql()` function: -```json {"Update typings to a ts file here:":7-8} title="tsconfig.json" -{ - "compilerOptions": { - "plugins": [ - { - "name": "@0no-co/graphqlsp", - "schema": "./schema.graphql", - - "tadaOutputLocation": "./src/introspection.ts" - } - ] - } -} -``` - -When opening the project, this will now create a `src/introspection.ts` file that only exports our -introspection query data, which we can use to initialize `gql.tada` manually. - -We’ll create a file that uses this introspection data and passes it to `gql.tada`: - -```ts title="src/graphql.ts" +```ts title="src/graphql.ts" {4-6} import { initGraphQLTada } from 'gql.tada'; -import type { introspection } from '../introspection'; +import type { introspection } from './graphql-env.d.ts'; export const graphql = initGraphQLTada<{ - introspection: typeof introspection; + introspection: introspection; }>(); export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada'; @@ -289,8 +274,10 @@ export { readFragment } from 'gql.tada'; ``` Instead of declaring our schema project-wide, we now have created a `graphql` function -that specifically uses the `introspection.ts` file that `@0no-co/graphqlsp` outputs -for us. Instead of importing `graphql` from `gql.tada`, we should now import it from our +that specifically uses the introspection inside the `graphql-env.d.ts` file that +`@0no-co/graphqlsp` outputs for us. + +Instead of importing `graphql` from `gql.tada`, we should now import it from our custom `src/graphql.ts` file. ### Customizing scalar types @@ -306,10 +293,10 @@ is a string. ```ts {"Define scalar types here:":6-10} title="src/graphql.ts" import { initGraphQLTada } from 'gql.tada'; -import type { introspection } from '../introspection'; +import type { introspection } from './graphql-env.d.ts'; export const graphql = initGraphQLTada<{ - introspection: typeof introspection; + introspection: introspection; scalars: { DateTime: string, diff --git a/website/src/content/docs/reference/gql-tada-api.mdx b/website/src/content/docs/reference/gql-tada-api.mdx index d7abf7b6..beb603a0 100644 --- a/website/src/content/docs/reference/gql-tada-api.mdx +++ b/website/src/content/docs/reference/gql-tada-api.mdx @@ -118,10 +118,10 @@ editor and the TypeScript language server to recognize your GraphQL documents co ```ts import { initGraphQLTada } from 'gql.tada'; -import type { myIntrospection } from './myIntrospection'; +import type { introspection } from './graphql-env.d.ts'; export const graphql = initGraphQLTada<{ - introspection: typeof myIntrospection; + introspection: introspection; scalars: { DateTime: string; Json: any; @@ -220,11 +220,11 @@ you may call [`initGraphQLTada()`](#initgraphqltada) instead. #### Example ```ts -import type { myIntrospection } from './myIntrospection'; +import type { introspection } from './graphql-env.d.ts'; declare module 'gql.tada' { interface setupSchema { - introspection: typeof myIntrospection; + introspection: introspection; scalars: { DateTime: string; Json: any; diff --git a/website/src/content/docs/reference/graphqlsp-config.mdx b/website/src/content/docs/reference/graphqlsp-config.mdx index cd13aa56..eb814c30 100644 --- a/website/src/content/docs/reference/graphqlsp-config.mdx +++ b/website/src/content/docs/reference/graphqlsp-config.mdx @@ -137,13 +137,14 @@ are used to save the introspection result: #### Format 1 — `.d.ts` file When writing a `.d.ts` file, `@0no-co/graphqlsp` will create a declaration file that automatically -declares [a `setupSchema` interface on `gql.tada`](../gql-tada-api/#setupschema) that, via [declaration merging in TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-merging.html), configures `gql.tada` to use a schema -project-wide for typings. Furthermore, this stops us from customizing the `scalars` option. +declares [a `setupSchema` interface on `gql.tada`](../gql-tada-api/#setupschema) that, +via [declaration merging in TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-merging.html), +configures `gql.tada` to use a schema project-wide for typings. The resulting file will have the following shape: ```ts title="graphql-env.d.ts" collapse={2-12} -declare const introspection: { +export type introspection = { "__schema": { "queryType": { "name": "Query" @@ -161,17 +162,34 @@ import * as gqlTada from 'gql.tada'; declare module 'gql.tada' { interface setupSchema { - introspection: typeof introspection + introspection: introspection } } ``` +If we want to now customize scalars, for instance, we’ll need to create our own `graphql()` function +by using the `introspection` type with [`gql.tada`’s `initGraphQLTada<>()` function](../gql-tada-api/#initgraphqltada): + +```ts title="graphql.ts" +import { initGraphQLTada } from 'gql.tada'; +import type { introspection } from './graphql-env.d.ts'; + +export const graphql = initGraphQLTada<{ + introspection: introspection; + scalars: { + DateTime: string, + JSON: any, + }, +}>(); +``` + [Read more on how to configure the `tadaOutputLocation` option, on the “Installation” page.](../../get-started/installation/#step-3-configuring-typings) #### Format 2 — `.ts` file When writing a `.ts` file instead, `@0no-co/graphqlsp` will create a regular TypeScript file that -exports an `introspection` object, ready to be used with [`gql.tada`’s `initGraphQLTada<>()` function](../gql-tada-api/#initgraphqltada). +exports an `introspection` object, which is useful if we’re planning on re-using the introspection +data during runtime. The resulting file will have the following shape: @@ -194,7 +212,8 @@ export { introspection }; ``` Hence, with this format it’s required to import the introspection and to create a [`graphql()` function](../gql-tada-api/#graphql) using -the [`initGraphQLTada<>()` function](../gql-tada-api/#initgraphqltada), passing the introspection type into the function’s generic. +the [`initGraphQLTada<>()` function](../gql-tada-api/#initgraphqltada). The introspection type won’t be set up project-wide, since the +`.ts` output from `@0no-co/graphqlsp` doesn’t contain a `declare module` declaration. [Read more on how to configure the `tadaOutputLocation` option, on the “Installation” page.](../../get-started/installation/#initializing-gqltada-manually)