Quick Start

This page gets you from a GraphQL schema to a generated TypeScript SDK. Follow the steps in order the first time; after that, use the sections as copy-paste references.

The shortest path is install packages, generate a client, create the client, then write one typed selection.

Install the packages

Add the CLI as a dev dependency. Add the runtime and GraphQL as app dependencies.

Generate a client

Point Gqlts at either a local schema file or an introspection endpoint.

Create a client

Import from the generated folder and pass your GraphQL endpoint.

Select fields

Write the fields you need as a TypeScript object and let the generated types follow the selection.

Pick the integration path

Use the generated client directly or generate operations for another request layer.

1. Install the packages

Choose the package manager your app already uses:


npm install -D @gqlts/cli
npm install @gqlts/runtime graphql


pnpm add -D @gqlts/cli
pnpm add @gqlts/runtime graphql


yarn add -D @gqlts/cli
yarn add @gqlts/runtime graphql


bun add -d @gqlts/cli
bun add @gqlts/runtime graphql

@gqlts/cli generates files. @gqlts/runtime and graphql are imported by the generated client.

2. Generate a client

Generate from a local SDL file when your schema is already in the repo:


npx gqlts --schema ./schema.graphql --output ./generated

Introspect an endpoint when your schema lives behind a running GraphQL server:


npx gqlts \
  --endpoint https://countries.trevorblades.com \
  --output ./generated \
  -H 'Authorization: Bearer myToken'

Equivalent runners work too:


pnpm dlx gqlts --schema ./schema.graphql --output ./generated
yarn gqlts --schema ./schema.graphql --output ./generated
bunx gqlts --schema ./schema.graphql --output ./generated

3. Create a client

Import from the generated folder and configure your endpoint:


import { createClient } from './generated';
 
const client = createClient({
  url: 'https://countries.trevorblades.com',
  headers: () => ({
    'x-client-name': 'docs-example',
  }),
});

Use a function for headers when tokens can change while the app is running.

4. Select fields

Pass a request object to client.query. The response type follows the selected fields:


const { data, errors } = await client.query({
  countries: [
    { filter: { continent: { eq: 'EU' } } },
    {
      name: true,
      code: true,
      languages: {
        name: true,
      },
    },
  ],
});
 
data?.countries[0].languages[0].name;

The request object above prints a normal GraphQL operation. The important part is that the data type only contains the fields you selected.

5. Choose your next page

I want to understand the request shape.

Read Request Objects for selections, arguments, aliases, and variables.

I want React patterns.

Read Usage in React for component-level usage and data fetching patterns.

I want custom transport.

Read Use with Other Clients when Apollo, SWR, React Query, or fetch owns the request.

I want generation options.

Read CLI Generation for schema input, endpoint headers, and output paths.

Generate operations without executing

Use this when Apollo, SWR, React Query, or a custom transport should own the request:


import { generateQueryOp } from './generated';
 
const operation = generateQueryOp({
  country: [{ code: 'CA' }, { name: true, emoji: true }],
});
 
await fetch('/graphql', {
  method: 'POST',
  body: JSON.stringify(operation),
});

Next steps

Read Examples and Recipes when you want integration patterns. Read Feature Coverage when you need to confirm support for a GraphQL feature.