### Install gql.tada from scratch (bun)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

When setting up gql.tada for the first time, only install the gql.tada package.

```sh
bun add gql.tada
```

--------------------------------

### Install gql.tada from scratch (npm)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

When setting up gql.tada for the first time, only install the gql.tada package.

```sh
npm install gql.tada
```

--------------------------------

### Install gql.tada from scratch (pnpm)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

When setting up gql.tada for the first time, only install the gql.tada package.

```sh
pnpm add gql.tada
```

--------------------------------

### Install gql.tada from scratch (yarn)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

When setting up gql.tada for the first time, only install the gql.tada package.

```sh
yarn add gql.tada
```

--------------------------------

### Install gql.tada package

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

Install the library as a dependency using your preferred package manager.

```npm
npm install gql.tada
```

```pnpm
pnpm add gql.tada
```

```yarn
yarn add gql.tada
```

```bun
bun add gql.tada
```

--------------------------------

### Install @urql/exchange-persisted

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/persisted-documents.md

Commands to install the @urql/exchange-persisted package using different package managers.

```sh
npm install @urql/exchange-persisted
```

```sh
pnpm add @urql/exchange-persisted
```

```sh
yarn add @urql/exchange-persisted
```

```sh
bun add @urql/exchange-persisted
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/0no-co/gql.tada/blob/main/CONTRIBUTING.md

Install project dependencies using pnpm. Ensure you use pnpm to respect the lockfile.

```sh
pnpm install
```

--------------------------------

### Install Vue and Svelte Support Packages

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

Install support packages to enable the gql-tada check command for Vue and Svelte files.

```sh
# for Vue
npm install -D @gql.tada/vue-support
# for Svelte
npm install -D @gql.tada/svelte-support
```

```sh
# for Vue
pnpm add -D @gql.tada/vue-support
# for Svelte
pnpm add -D @gql.tada/svelte-support
```

```sh
# for Vue
yarn add -D @gql.tada/vue-support
# for Svelte
yarn add -D @gql.tada/svelte-support
```

```sh
# for Vue
bun add -d @gql.tada/vue-support
# for Svelte
bun add -d @gql.tada/svelte-support
```

--------------------------------

### Install @0no-co/graphqlsp for Legacy TypeScript

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

Install the plugin package directly when using TypeScript versions older than 5.5.

```sh
npm install --save-dev @0no-co/graphqlsp
```

```sh
pnpm add --save-dev @0no-co/graphqlsp
```

```sh
yarn add --dev @0no-co/graphqlsp
```

```sh
bun add --dev @0no-co/graphqlsp
```

--------------------------------

### CLI Command: init

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

Initializes a new gql-tada project by locating the schema, configuring tsconfig.json, and installing dependencies.

```APIDOC
## CLI Command: init

### Description
Initializes a gql-tada project. This command locates the schema, sets up the graphql-env.d.ts file, configures tsconfig.json, and installs necessary dependencies.

### Parameters
#### Path Parameters
- **dir** (string) - Required - A relative location from your current working directory where the project should be initialized.
```

--------------------------------

### Persisted Manifest File Example

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/persisted-documents.md

A JSON file containing document entries keyed by document ID, with GraphQL documents as values. This example shows a 'POKEMONS_LIST_ID' entry.

```json
{
  "POKEMONS_LIST_ID": "\n  query Pokemons ($limit: Int = 10) {\n    pokemons(limit: $limit) {\n      id\n      name\n    }\n  }\n\n\nfragment PokemonItem on Pokemon {\n  id\n  name\n}"
}
```

--------------------------------

### Initialize gql-tada Project with npm

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

Use this command to set up a new gql-tada project. It handles schema location, configuration, and dependency installation.

```sh
npx gql-tada init ./my-project
```

--------------------------------

### Initialize gql-tada Project with bun

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

Use this command to set up a new gql-tada project. It handles schema location, configuration, and dependency installation.

```sh
bunx gql-tada init ./my-project
```

--------------------------------

### Initialize gql-tada Project with pnpm

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

Use this command to set up a new gql-tada project. It handles schema location, configuration, and dependency installation.

```sh
pnpx gql-tada init ./my-project
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/typed-documents.md

A sample GraphQL query to retrieve data from the defined schema.

```graphql
query {
  helloWorld
  numberOfRequests
}
```

--------------------------------

### GitHub Actions CI Step

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Example step for running gql-tada checks within a GitHub Actions workflow.

```yaml
- name: "gql.tada Checks"
  run: |
    gql-tada generate output
    gql-tada check
```

--------------------------------

### CLI Command: doctor

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

Checks for common setup and configuration mistakes in a gql-tada project.

```APIDOC
## CLI Command: doctor

### Description
Performs a health check on the gql-tada setup. It verifies installed package versions, configuration settings, and the schema integrity.
```

--------------------------------

### GitHub Actions Verification Step

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Example GitHub Actions step to verify that generated files match the committed versions.

```yaml
- name: "gql.tada Checks"
  run: |
    gql-tada generate output
    gql-tada generate turbo
    git diff --name-status --exit-code .
```

--------------------------------

### Run Doctor Command

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Execute the doctor command to verify configuration and environment setup.

```sh
gql-tada doctor
```

--------------------------------

### Check gql-tada Configuration

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

The `doctor` command checks for common setup and configuration mistakes in your gql-tada project.

```sh
npx gql-tada doctor
```

--------------------------------

### Sample JSON Response

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/typed-documents.md

An example of a JSON response that matches the GraphQL query and schema.

```json
{
  "helloWorld": "Hello!",
  "numberOfRequests: 1
}
```

--------------------------------

### GraphQL Query Execution with Fetch

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/typed-documents.md

Demonstrates a basic client-side implementation of executing a GraphQL query using the fetch API in TypeScript. Ensure the 'graphql' library is installed for 'parse' and 'print' functions.

```typescript
import { DocumentNode, parse, print } from 'graphql';

const query = parse(/* GraphQL */ `
  {
    helloWorld
    numberOfRequests
  }
`);

async function execute(query: DocumentNode, variables?: any): Promise<any> {
  const response = await fetch('/graphql', {
    method: 'POST',
    body: JSON.stringify({
      query: print(query),
      variables,
    }),
  });
  return (await response.json()).data;
}

const data = await execute(query);
```

--------------------------------

### Example generated graphql-env.d.ts

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

The structure of the generated typings file that provides schema introspection to the TypeScript type system.

```ts
declare const introspection: {
  __schema: { /*...*/ };
};

import * as gqlTada from 'gql.tada';

declare module 'gql.tada' {
  interface setupSchema {
    introspection: typeof introspection;
  }
}
```

--------------------------------

### Example of Fragment Masking Issue

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/fragment-colocation.md

This example demonstrates how a component can accidentally depend on data from another fragment when `@_unmask` is used, leading to potential data leaks.

```tsx
// @filename: PokemonTypes.tsx
import './graphql/graphql-env.d.ts';
import { FragmentOf, graphql } from 'gql.tada';

export const pokemonTypesFragment = graphql(
  """fragment PokemonTypes on Pokemon @_unmask {
    types
  }"""
);

export const PokemonTypes = (props: {
  data: FragmentOf<typeof pokemonTypesFragment>
}) => null;
// @filename: Pokemon.tsx
import { FragmentOf, graphql } from 'gql.tada';
import { pokemonTypesFragment, PokemonTypes } from './PokemonTypes';

export const pokemonFragment = graphql(
  """fragment Pokemon on Pokemon @_unmask {
    id
    name
    ...PokemonTypes
  }""",
  [pokemonTypesFragment]
);
// ---cut-before---
export const Pokemon = (props: {
  data: FragmentOf<typeof pokemonFragment>
}) => {
  const { data } = props;
  return (
    <section>
      <p>{data.name}</p>
// @error: Pokemon now accidentally depends on PokemonTypes’s data:

      <span>{data.types?.length}</span>
      <PokemonTypes data={data} />
    </section>
  );
};

```

--------------------------------

### Create a Changeset File

Source: https://github.com/0no-co/gql.tada/blob/main/CONTRIBUTING.md

Use this command in the root of the repository to create a new changeset file. This file documents changes for changelog generation and version bumping.

```bash
pnpm changeset
```

--------------------------------

### Execute gql-tada CLI commands

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/multiple-schemas.md

Standard CLI commands for checking and generating artifacts.

```sh
gql-tada check
gql-tada generate output
gql-tada generate turbo
gql-tada generate persisted
```

--------------------------------

### Enable Turbo Mode via CLI

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-04-15.md

Commands to generate a cached typings file for GraphQL documents to improve type inference performance.

```npm
npm gql.tada turbo
```

```pnpm
pnpm gql.tada turbo
```

```yarn
yarn gql.tada turbo
```

```bun
bun run gql.tada turbo
```

--------------------------------

### Define a hashed persisted document ID

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/persisted-documents.md

Example of a persisted query using a SHA256 hash as the document identifier.

```ts
const persistedQuery = graphql.persisted(
  "sha256:89e47d4f32b4ff76296844ff260d2878bf1829d30706fc7fc92de0fc66c2a4cf",
  pokemonsQuery
);
```

--------------------------------

### Usage of schema-specific graphql() function

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/multiple-schemas.md

Demonstrates importing and using a previously initialized graphql() function for a specific schema.

```ts
// @filename: src/graphql/simple-env.d.ts
export type introspection = {
  name: 'simple';
  query: 'Query';
  types: {
    String: unknown;
    Query: {
      kind: 'OBJECT';
      name: 'Query';
      fields: {
        helloWorld: {
          name: 'helloWorld';
          type: {
            kind: 'SCALAR';
            name: 'String';
            ofType: null;
          };
        };
      };
    };
  };
};
// @filename: src/graphql/simple.ts
// ---cut---
import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './simple-env.d.ts';

export const graphql = initGraphQLTada<{
  introspection: introspection;
}>();
// @filename: src/index.ts
// ---cut---
import { graphql } from './graphql/simple';

const query = graphql(`
  { helloWorld }
`);
```

--------------------------------

### Define manual result and variable types

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/typed-documents.md

Example of a generated file containing TypeScript types for a GraphQL query result and its variables.

```ts
export type Result = {
  helloWorld: string | null;
  numberOfRequests: number;
};

export type Variables = {};
```

--------------------------------

### CLI Command: generate-schema

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

Introspects a GraphQL API or file and outputs a .graphql SDL file.

```APIDOC
## CLI Command: generate-schema

### Description
Introspects a targeted GraphQL API URL, .graphql SDL, or introspection JSON file and writes the result to a .graphql SDL file.

### Parameters
#### Path Parameters
- **schema** (string) - Required - URL to a GraphQL API or path to a .graphql SDL/introspection JSON file.

#### Query Parameters
- **--tsconfig, -c** (string) - Optional - Path to a tsconfig.json file.
- **--output, -o** (string) - Optional - Output location for the .graphql SDL file.
- **--header** (string) - Optional - Key:value header entry for API introspection requests.
```

--------------------------------

### Download GraphQL Schema with Headers

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Pass authentication headers using the --header flag during schema introspection.

```sh
gql-tada generate schema 'http://api.test/graphql' --header "Authorization: $ENV_TOKEN"
```

--------------------------------

### Generate GraphQL Schema via CLI

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-04-15.md

Commands to introspect a GraphQL API and generate an SDL file using various package managers.

```npm
npm gql.tada generate schema 'https://api.github.com/graphql'
```

```pnpm
pnpm gql.tada generate schema 'https://api.github.com/graphql'
```

```yarn
yarn gql.tada generate schema 'https://api.github.com/graphql'
```

```bun
bun run gql.tada generate schema 'https://api.github.com/graphql'
```

--------------------------------

### Detect unused GraphQL fields

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

This example demonstrates how a `maxHP` field, present in the GraphQL fragment but not used in the component's code, triggers a warning when `trackFieldUsage` is enabled.

```tsx
import './graphql/graphql-env.d.ts';
// ---cut-before---
import { FragmentOf, graphql, readFragment } from 'gql.tada';

// @warn: GraphQLSP: Field 'maxHP is not used.

export const PokemonItemFragment = graphql(`
  fragment PokemonItem on Pokemon {
    id
    name
    maxHP
  }
`);

interface Props {
  data: FragmentOf<typeof PokemonItemFragment>;
}

export const PokemonItem = ({ data }: Props) => {
  const pokemon = readFragment(PokemonItemFragment, data);
  return <li></li>;
};
```

--------------------------------

### Download GraphQL Schema via CLI

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Use the generate schema command to introspect an API and save the schema to a file.

```sh
gql-tada generate schema 'http://api.test/graphql' --output './schema.graphql'
```

--------------------------------

### Automatic Persisted Queries Protocol JSON Structure

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/persisted-documents.md

An example JSON structure for the Automatic Persisted Queries protocol, used when omitting the 'query' property and sending the document ID under 'extensions.persistedQuery.sha256Hash'.

```json
{
  "variables": null,
  "extensions": {
    "persistedQuery": {
      "version": 1,
      "sha256Hash": "DOCUMENT_ID"
    }
  }
}
```

--------------------------------

### Basic tsconfig.json Configuration

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

This snippet shows the basic configuration for gql.tada within tsconfig.json, specifying a single schema and output location.

```APIDOC
## Basic tsconfig.json Configuration

### Description
This configuration sets up the gql.tada TypeScript plugin with a single schema file and defines the output location for generated type definitions.

### Method
N/A (Configuration File)

### Endpoint
N/A (Configuration File)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```json
{
  "compilerOptions": {
    "strict": true,
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./schema.graphql",
        "tadaOutputLocation": "./src/graphql-env.d.ts"
      }
    ]
  }
}
```

### Response
N/A (Configuration File)
```

--------------------------------

### Detect missing co-located fragment imports

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

This example shows a warning generated when a GraphQL fragment is exported by another module (`PokemonItem.tsx`) but not imported and used in the current file (`PokemonsList.tsx`), assuming `shouldCheckForColocatedFragments` is enabled.

```tsx
import './graphql/graphql-env.d.ts';
// ---cut-before---
// @filename: ./src/PokemonItem.tsx
export const PokemonItem = () => null;
// @filename: ./src/PokemonsList.tsx
// ---cut---
import { useQuery } from 'urql';
import { graphql } from 'gql.tada';

// @warn: GraphQLSP: Unused co-located fragment definition(s)
import { PokemonItem } from './PokemonItem';

const PokemonsQuery = graphql(`
  query Pokemons($limit: Int = 10) {
    pokemons(limit: $limit) {
      id
      name
    }
  }
`, []);

export const PokemonList = () => {
  const [result] = useQuery({ query: PokemonsQuery });
  return null; // ...
};
```

--------------------------------

### Generate a persisted manifest

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-04-15.md

Run the CLI command to scan the codebase and extract persisted documents into a JSON manifest.

```sh
gql.tada generate persisted -o persisted.json
```

--------------------------------

### Setup GraphQL Schema with Custom Scalars

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-api.md

Use this to declare your GraphQL schema introspection and custom scalar types for gql.tada. Ensure the 'introspection' type matches your schema and 'scalars' maps scalar names to their TypeScript types.

```typescript
import type { introspection } from './graphql/graphql-env.d.ts';

declare module 'gql.tada' {
  interface setupSchema {
    introspection: introspection;
    scalars: {
      DateTime: string;
      Json: any;
    };
  }
}
```

--------------------------------

### Run Project Commands

Source: https://github.com/0no-co/gql.tada/blob/main/CONTRIBUTING.md

Common commands to run in the root folder for development tasks like TypeScript checks, linting, testing, and building.

```sh
# TypeScript checks:
pnpm run check

# Linting (prettier & eslint):
pnpm run lint

# Unit Tests (for all packages):
pnpm run test

# Builds (for all packages):
pnpm run build
```

--------------------------------

### Basic gql.tada Query with Type Inference

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/typed-documents.md

Demonstrates creating a fully typed GraphQL document using gql.tada's `graphql` tag. No extra imports are needed for type inference.

```ts
// @filename: index.ts
import './graphql-env.d.ts';
// ---cut---
import { graphql } from 'gql.tada';

// @annotate: We get a TypedDocumentNode without extra imports

const query = graphql(`
  {
    helloWorld
    numberOfRequests
  }
`);
```

--------------------------------

### Generate Changelog Documentation

Source: https://github.com/0no-co/gql.tada/blob/main/CONTRIBUTING.md

Document a change for the changelog using the 'changeset' command. This process involves specifying changed packages and the type of change (major/minor/patch), followed by writing a markdown entry.

```sh
changeset
```

--------------------------------

### Run CI Checks

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Execute generation and check commands in a CI environment.

```sh
gql-tada generate output
gql-tada check
```

--------------------------------

### Run Turbo Mode

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Execute the turbo command to scan the codebase and generate a type cache.

```sh
gql-tada turbo
```

--------------------------------

### Configure TypeScript plugin

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

Add the gql.tada plugin to your tsconfig.json to enable language server features.

```json
{
  "compilerOptions": {
    "strict": true,
    "plugins": [ // [!code ++]
      { // [!code ++]
        "name": "gql.tada/ts-plugin", // [!code ++]
        "schema": "./schema.graphql", // [!code ++]
        "tadaOutputLocation": "./src/graphql-env.d.ts" // [!code ++]
      } // [!code ++]
    ] // [!code ++]
  }
}
```

--------------------------------

### Initializing GraphQL Tada

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-api.md

The `initGraphQLTada` function is used to set up a typed `graphql` function based on your schema. It accepts a generic configuration object for schema introspection and scalar types.

```APIDOC
## `initGraphQLTada()`

### Description
Initializes and returns a typed `graphql` function.

### Method
Function Call

### Parameters
#### Generic Parameter
- **Setup** (AbstractSetupSchema) - Required - An AbstractSetupSchema configuration object.

### Returns
- A typed `graphql` function.

### Example
```ts
import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './graphql/graphql-env.d.ts';

export const graphql = initGraphQLTada({
  introspection: introspection
});

const query = graphql(`
  {
    __typename
  }
`);
```
```

--------------------------------

### Initialize graphql() for Pokemon schema

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/multiple-schemas.md

Creates a schema-specific graphql() function using the Pokemon introspection type.

```ts
// @filename: pokemon-env.d.ts
export type introspection = import('./graphql/graphql-env.d.ts').introspection;
// @filename: index.ts
// ---cut---
import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './pokemon-env.d.ts';

export const graphql = initGraphQLTada<{
  introspection: introspection;
}>();
```

--------------------------------

### Configure gql.tada in tsconfig.json

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

Define the plugin name and output location for the generated typings file within the compilerOptions of your tsconfig.json.

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
// @annotate: Configure the output typings file location here
        "schema": "./schema.graphql",
        "tadaOutputLocation": "./src/graphql-env.d.ts"
      }
    ]
  }
}
```

--------------------------------

### Run workspace diagnostics

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Executes the CLI command to perform GraphQL validation and schema-related checks across the entire workspace.

```sh
gql-tada check
```

--------------------------------

### Upgrade gql.tada and Remove graphqlsp (bun)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

Use this command to upgrade gql.tada and remove the separate graphqlsp dependency when upgrading from a previous version.

```sh
bun remove @0no-co/graphqlsp
bun add gql.tada@^1.8.0
```

--------------------------------

### Initialize GraphQL Tada

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-api.md

Initialize `graphql` function with schema introspection and scalar types. Re-export the function as `graphql` or `gql` for editor recognition.

```ts
import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './graphql/graphql-env.d.ts';

export const graphql = initGraphQLTada<{ 
  introspection: introspection;
  scalars: {
    DateTime: string;
    Json: any;
  };
}>();

const query = graphql(`
  {
    __typename
  }
`);
```

--------------------------------

### Initialize GraphQL Tada manually

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-04-26.md

Use initGraphQLTada to create a graphql function for each schema. This must be done separately for every schema defined in the configuration.

```ts
import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './graphql/graphql-env.d.ts';

export const graphql = initGraphQLTada<{
  introspection: introspection;
}>();

export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
export { readFragment } from 'gql.tada';
```

--------------------------------

### Specify Schema via Local .graphql File

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

Configure gql.tada to load the schema from a local .graphql file using the 'schema' option.

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./schema.graphql"
      }
    ]
  }
}
```

--------------------------------

### Schema Option: tadaOutputLocation

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

Details on configuring the `tadaOutputLocation` option, which specifies the output path for generated type definition files.

```APIDOC
## Schema Option: tadaOutputLocation

### Description
The `tadaOutputLocation` option is required and specifies the path where gql.tada will write the generated type definition file (`.d.ts` or `.ts`). If a directory is provided, a default filename will be used.

### Method
N/A (Configuration Option)

### Endpoint
N/A (Configuration Option)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "tadaOutputLocation": "./src/graphql-env.d.ts"
      }
    ]
  }
}
```

### Response
N/A (Configuration Option)
```

--------------------------------

### Schema Option: schema

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

Details on configuring the `schema` option, which specifies how to load the GraphQL schema.

```APIDOC
## Schema Option: schema

### Description
The `schema` option is required and defines how gql.tada loads your GraphQL schema. It supports file paths to `.graphql` or `.json` files, or a URL to an introspectable GraphQL API.

### Method
N/A (Configuration Option)

### Endpoint
N/A (Configuration Option)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./schema.graphql" 
      }
    ]
  }
}
```

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./introspection.json"
      }
    ]
  }
}
```

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "http://localhost:4321/graphql"
      }
    ]
  }
}
```

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": {
          "url": "http://localhost:4321/graphql",
          "headers": {
            "Accept": "application/graphql-response+json"
          }
        }
      }
    ]
  }
}
```

### Response
N/A (Configuration Option)
```

--------------------------------

### Generate GraphQL Schema

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

Introspects a GraphQL API or reads from a file to generate a `.graphql` SDL file. Useful when avoiding direct schema URL configuration.

```sh
npx gql-tada generate-schema <schema> --output <output>
```

--------------------------------

### Generate a persisted manifest via CLI

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/persisted-documents.md

Command to scan the codebase for persisted GraphQL documents and extract them into a JSON file.

```sh
gql-tada generate persisted --output persisted.json
```

--------------------------------

### Initialize graphql() for simple schema

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/multiple-schemas.md

Creates a schema-specific graphql() function using a custom introspection type definition.

```ts
// @filename: simple-env.d.ts
export type introspection = {
  name: 'simple';
  query: 'Query';
  types: {
    String: unknown;
    Query: {
      kind: 'OBJECT';
      name: 'Query';
      fields: {
        helloWorld: {
          name: 'helloWorld';
          type: {
            kind: 'SCALAR';
            name: 'String';
            ofType: null;
          };
        };
      };
    };
  };
};
// @filename: index.ts
// ---cut---
import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './simple-env.d.ts';

export const graphql = initGraphQLTada<{
  introspection: introspection;
}>();
```

--------------------------------

### Urql Core Client Integration with gql.tada

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/typed-documents.md

Demonstrates using a gql.tada TypedDocumentNode with the core urql client for making queries.

```ts
import './graphql/graphql-env.d.ts';
declare var client: import('@urql/core').Client;
// ---cut-before---
import { graphql } from 'gql.tada';

const getPokemonsQuery = graphql(`
  query GetPokemons {
    pokemons {
      id
      name
    }
  }
`);

async function getPokemons() {
  const { data } = await client.query(getPokemonsQuery, {});
}
```

--------------------------------

### Check Changeset Status

Source: https://github.com/0no-co/gql.tada/blob/main/CONTRIBUTING.md

Before a release, use this command to review the current changes that are staged to be included in the next release. This helps in verifying what will appear in the changelog.

```bash
pnpm changeset status
```

--------------------------------

### Define .d.ts introspection file

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

Use this format to automatically declare the setupSchema interface for gql.tada via TypeScript declaration merging.

```ts
export type introspection = {
  __schema: { /*...*/ };
};

import * as gqlTada from 'gql.tada';

declare module 'gql.tada' {
  interface setupSchema {
    introspection: introspection;
  }
}
```

--------------------------------

### generateOutput()

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-cli.md

The generateOutput() function outputs the gql.tada output file manually. It loads the schema from the specified schema configuration option and writes the output file.

```APIDOC
## generateOutput()

### Description
Outputs the gql.tada output file manually. It loads the schema from the specified `schema` configuration option and writes the output file.

### Method
`generateOutput`

### Parameters
#### Options
- **output** (string) - Optional - The filename to write the output file to (Default: the `tadaOutputLocation` configuration option)
- **tsconfig** (string) - Optional - The `tsconfig.json` to use instead of an automatically discovered one.
- **disablePreprocessing** (boolean) - Optional - Whether to disable the optimized output format for `.d.ts` files.

### Returns
A `Promise` that resolves when the task completes.

### Request Example
```ts
import { generateOutput } from '@gql.tada/cli-utils';

await generateOutput({
  output: './src/graphql-env.d.ts',
  disablePreprocessing: false,
  tsconfig: undefined,
});
```
```

--------------------------------

### Specify Schema via Local .json File

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

Configure gql.tada to load the schema from a local .json file containing introspection data.

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./introspection.json"
      }
    ]
  }
}
```

--------------------------------

### Configure schema output locations in tsconfig.json

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/multiple-schemas.md

Define output paths for multiple schemas within the gql.tada TypeScript plugin configuration.

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schemas": [
          {
            "name": "pokemon",
            "schema": "./graphql/pokemon.graphql",
            "tadaOutputLocation": "./src/graphql/pokemon-env.d.ts",
            "tadaTurboLocation": "./src/graphql/pokemon-cache.d.ts",
            "tadaPersistedLocation": "./graphql/pokemon-persisted.json"
          },
          /*...*/
        ]
      }
    ]
  }
}
```

--------------------------------

### Configure tsconfig.json for GraphQLSP

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

Update the plugins section in tsconfig.json to use @0no-co/graphqlsp instead of the default alias.

```json
{
  "compilerOptions": {
    "strict": true,
    "plugins": [
      {
        "name": "gql.tada/ts-plugin", // [!code --]
        "name": "@0no-co/graphqlsp", // [!code ++]
        "schema": "./schema.graphql",
        "tadaOutputLocation": "./src/graphql-env.d.ts"
      }
    ]
  }
}
```

--------------------------------

### Schema Configuration

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/gql-tada-api.md

You can configure GraphQL Tada's type inference by extending the `setupSchema` interface with your GraphQL schema introspection data and custom scalars.

```APIDOC
### `setupSchema`

#### Description
Allows extending the schema configuration for type inference. You can declare your `IntrospectionQuery` data and scalars here.

#### Usage
Declare an interface for `setupSchema` in your project's type definitions to merge your schema and scalar information.
```

--------------------------------

### Upgrade gql.tada and Remove graphqlsp (yarn)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

Use this command to upgrade gql.tada and remove the separate graphqlsp dependency when upgrading from a previous version.

```sh
yarn remove @0no-co/graphqlsp
yarn add gql.tada@^1.8.0
```

--------------------------------

### Define a GraphQL Fragment

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/writing-graphql.md

Create a GraphQL fragment using the `graphql()` function. The type of the fragment is inferred from its definition.

```typescript
import './graphql/graphql-env.d.ts';
// ---cut-before---
import { graphql } from 'gql.tada';

const PokemonFragment = graphql(`
  fragment Pokemon on Pokemon {
    id
    name
    collected
  }
`);
```

--------------------------------

### Upgrade gql.tada and Remove graphqlsp (pnpm)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

Use this command to upgrade gql.tada and remove the separate graphqlsp dependency when upgrading from a previous version.

```sh
pnpm remove @0no-co/graphqlsp
pnpm add gql.tada@^1.8.0
```

--------------------------------

### Configure urql Client with Persisted Exchange

Source: https://github.com/0no-co/gql.tada/blob/main/website/guides/persisted-documents.md

Configures the urql client to use the persistedExchange, enabling Automatic Persisted Queries. It specifies how to generate the hash and configures options like preferGetForPersistedQueries and enforcePersistedQueries.

```typescript
import type { TadaPersistedDocumentNode } from 'gql.tada';
import { Client, fetchExchange, cacheExchange } from 'urql';
import { persistedExchange } from '@urql/exchange-persisted';

export const client = new Client({
  url: '/graphql',
  exchanges: [
    cacheExchange,
    persistedExchange({
      async generateHash(_, document) {
        return (document as TadaPersistedDocumentNode).documentId;
      },
      preferGetForPersistedQueries: true,
      enforcePersistedQueries: true,
      enableForMutation: true,
      enableForSubscriptions: true,
    }),
    fetchExchange,
  ],
});
```

--------------------------------

### Verify Committed Output Files

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Commands to generate files and verify they are up-to-date using git diff.

```sh
gql-tada generate-output
gql-tada turbo
git diff --name-status --exit-code .
```

--------------------------------

### Configure schema sources

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/installation.md

The schema option supports various formats including local files, introspection JSON, and remote URLs.

```.graphql file
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./schema.graphql"
      }
    ]
  }
}
```

```.json file
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "./introspection.json"
      }
    ]
  }
}
```

```URL
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": "http://localhost:4321/graphql"
      }
    ]
  }
}
```

```URL with headers
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": {
          "url": "http://localhost:4321/graphql",
          "headers": {
            "Accept": "application/graphql-response+json"
          }
        }
      }
    ]
  }
}
```

--------------------------------

### Upgrade gql.tada and Remove graphqlsp (npm)

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-06-26.md

Use this command to upgrade gql.tada and remove the separate graphqlsp dependency when upgrading from a previous version.

```sh
npm uninstall --save-dev @0no-co/graphqlsp
npm install gql.tada@^1.8.0
```

--------------------------------

### Specify Schema via URL with Headers

Source: https://github.com/0no-co/gql.tada/blob/main/website/reference/config-format.md

Configure gql.tada to load the schema from a GraphQL API endpoint with custom headers.

```json
{
  "compilerOptions": {
    "plugins": [
      {
        "name": "gql.tada/ts-plugin",
        "schema": {
          "url": "http://localhost:4321/graphql",
          "headers": {
            "Accept": "application/graphql-response+json"
          }
        }
      }
    ]
  }
}
```

--------------------------------

### Generate introspection typings

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/workflows.md

Executes the CLI command to load the schema and save the output typings file based on the configuration.

```sh
gql-tada generate output
```

--------------------------------

### Configure Custom Scalars

Source: https://github.com/0no-co/gql.tada/blob/main/website/get-started/writing-graphql.md

Initialize gql.tada with a custom mapping for the ID scalar to enforce a specific string format.

```ts
import { initGraphQLTada } from 'gql.tada';
import type { introspection } from './graphql/graphql-env.d.ts';

// ---cut-before---
export const graphql = initGraphQLTada<{
  introspection: introspection;
// @annotate: The ID type now takes on a special type
  scalars: {
    ID: `${number}`;
  };
}>();

export type { FragmentOf, ResultOf, VariablesOf } from 'gql.tada';
export { readFragment } from 'gql.tada';
```

--------------------------------

### Create a persisted operation by type

Source: https://github.com/0no-co/gql.tada/blob/main/website/devlog/2024-04-15.md

Pass the query by type to allow for tree-shaking and minification of the original document in the output bundle.

```ts
// @filename: graphq-env.d.ts
export type introspection = {
  __schema: {
    queryType: {
      name: 'Query';
    };
    mutationType: null;
    subscriptionType: null;
    types: [
      {
        kind: 'OBJECT';
        name: 'Query';
        fields: [
          {
            name: 'hello';
            type: {
              kind: 'SCALAR';
              name: 'String';
              ofType: null;
            };
            args: [];
          },
          {
            name: 'world';
            type: {
              kind: 'SCALAR';
              name: 'String';
              ofType: null;
            };
            args: [];
          },
        ];
        interfaces: [];
      },
      {
        kind: 'SCALAR';
        name: 'String';
      },
    ];
    directives: [];
  };
};

import * as gqlTada from 'gql.tada';

declare module 'gql.tada' {
  interface setupSchema {
    introspection: introspection;
  }
}

// @filename: index.ts
// ---cut-before---
import { graphql } from 'gql.tada';

const HelloQuery = graphql(`
  query Hello {
    hello
  }
`);

const HelloQueryPersisted = graphql.persisted<typeof HelloQuery>('sha256:x');
```