docs: Prefer instructions that only create .d.ts file (#27)

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,48 +253,31 @@ 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';
 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,

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;

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)