Using Callsheet with GraphQL

Callsheet works great with manually typed GraphQL documents, but it shines when you point it at generated documents from GraphQL Code Generator.

With generated documents, the workflow is pretty simple:

Point Callsheet at your generated documents

Generate your Callsheet

Use your calls through your adapter.

Walkthrough

First, if you haven't already, install your adapter package and @callsheet/codegen:

pnpm add @callsheet/react-query
pnpm add -D @callsheet/codegen

npm install @callsheet/react-query
npm install -D @callsheet/codegen

yarn add @callsheet/react-query
yarn add @callsheet/codegen -D

pnpm add @callsheet/swr
pnpm add -D @callsheet/codegen

npm install @callsheet/swr
npm install -D @callsheet/codegen

yarn add @callsheet/swr
yarn add @callsheet/codegen -D

Add generated documents

If you haven't already set up GraphQL Code Generator, do that first so it can generate the typed GraphQL documents Callsheet will read from.

Next, configure Callsheet to read from your generated documents:

callsheet.config.ts

import { defineConfig } from '@callsheet/codegen';

export default defineConfig({
  sources: {
    graphql: [
      {
        rootDir: './src/graphql',
        tsconfigFile: './tsconfig.json',
        entries: ['generated.ts'],
      },
    ],
  },
  output: {
    adapter: 'react-query',
    file: './src/generated/calls.ts',
  },
});

If your app uses SWR, set the output adapter to swr instead:

callsheet.config.ts

export default defineConfig({
  // ...
  output: {
    file: './src/generated/calls.ts',
    adapter: 'swr',
  },
});

Build Callsheet

Then build Callsheet from your generated docs. It creates a calls module you can import and use.

pnpm callsheet-codegen --config callsheet.config.ts

Output

This generates src/generated/calls.ts.

If you need to, you can change the output location in callsheet.config.ts.

Use generated calls

Once generated, import the calls module and use it through your adapter:

src/FilmPage.tsx

import { queryOptions, useQuery } from '@callsheet/react-query';
import { calls } from './generated/calls';

const film = useQuery(
  queryOptions(calls.filmById, {
    input: { id: 'wall-e' },
    select: (data) => data.film,
  }),
);

src/FilmPage.tsx

import { useQuery } from '@callsheet/swr';
import { calls } from './generated/calls';

const { data: film } = useQuery(calls.filmById, {
  input: { id: 'wall-e' },
});

Read more about the shared call surface in Calls.

Without GraphQL Code Generator

If you are not using GraphQL Code Generator, Callsheet still works with your typed GraphQL documents. Just define your Callsheet yourself instead of auto-generating it.

src/calls.ts

import { defineCalls, query } from '@callsheet/react-query';
import { FilmByIdDocument } from './graphql/film-by-id';

export const calls = defineCalls({
  films: {
    byId: query(FilmByIdDocument),
  },
});

src/calls.ts

import { defineCalls, query } from '@callsheet/swr';
import { FilmByIdDocument } from './graphql/film-by-id';

export const calls = defineCalls({
  films: {
    byId: query(FilmByIdDocument),
  },
});

In either setup, generated or manual, Callsheet gives you one shared call surface. Learn more in Calls, Using Callsheet with React Query, Using Callsheet with SWR, and Call Family and Identity.

If you want a deeper breakdown of the available codegen settings, go to Codegen Config.