Callsheet

Config shape

The config file exports a defineConfig(...) call with three top-level fields:

callsheet.config.ts

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

export default defineConfig({
  sources: {
    graphql: [
      /* ... */
    ],
    tsRest: [
      /* ... */
    ],
  },
  output: {
    file: './src/generated/calls.ts',
  },
  overrides: [
    /* ... */
  ],
});

Field	Required	Description
`sources`	Yes	Where Callsheet discovers typed operations
`output`	Yes	Where the generated module is written
`overrides`	No	Override the shape of generated entries

sources.graphql

Each entry in sources.graphql tells Callsheet where to find GraphQL document exports.

graphql: [
  {
    rootDir: './src/graphql',
    tsconfigFile: './tsconfig.json',
    entries: ['generated.ts'],
  },
],

Field	Required	Description
`rootDir`	Yes	Root directory for entry / namespace resolution
`tsconfigFile`	Yes	TypeScript config used for module resolution and exports
`entries`	Yes	File paths or glob patterns relative to `rootDir`
`exclude`	No	Glob patterns relative to `rootDir` to exclude from entry matches
`exportSuffix`	No	Suffix used to identify GraphQL document exports. Defaults to `Document`
`pathPrefix`	No	Prefix added to all discovered entries from this source

Callsheet entries can be specific files or globs like **/*.ts. Exports matching the exportSuffix are treated as GraphQL documents.

sources.tsRest

Each entry in sources.tsRest points Callsheet at a ts-rest contract export.

tsRest: [
  {
    importFrom: './src/rest/contract',
    exportName: 'contract',
    pathPrefix: ['rest'],
  },
],

Field	Required	Description
`importFrom`	Yes	Path to the module that exports the contract
`exportName`	Yes	Name of the contract export in that module
`pathPrefix`	No	Prefix added to all discovered routes from this source

Callsheet walks the contract and infers whether each route is a query or mutation based on the ts-rest route definition.

output

Config for the generated calls module.

output: {
  file: './src/generated/calls.ts',
  exportName: 'calls',
  importFrom: '@callsheet/react-query',
},

Field	Required	Description
`file`	Yes	Output file path for the generated module
`exportName`	No	Name of the exported calls object. Defaults to `calls`
`importFrom`	No	Package the generated module imports Callsheet builders from. Defaults to `@callsheet/react-query`

overrides

Overrides let you reshape generated entries when default discovery doesn't match the tree structure you want.

overrides: [
  {
    path: ['featuredFilms'],
    as: ['films', 'featured'],
    kind: 'query',
    options: {
      from: '../callsheet-options/films',
      name: 'featuredFilmsOptions',
    },
  },
],

Field	Required	Description
`path`	Yes	The generated path to target
`as`	No	Move the entry to a different path in the final tree
`kind`	No	Force `query` or `mutation` when discovery can't infer it
`options`	No	Import call options (like `family` or `invalidates`) from another module
`entry`	No	Narrow the override to a specific source entry when multiple entries share the same path

options takes an object with from (module path) and name (export name). The referenced module should export a call options object that gets passed as the second argument to the builder.

Use entry when multiple generated entries share the same path and the override should only apply to one of them.

When overrides are useful

Renaming: Use as when a generated path like featuredFilms should live at films.featured in the tree.
Forcing kind: Use kind when a GraphQL document doesn't have enough information for Callsheet to tell whether it's a query or mutation.
Attaching options: Use options when a generated call should include shared defaults like family, staleTime, or invalidates that live in a separate module.

Running codegen

Callsheet can automatically build itself using the callsheet-codegen CLI. It reads your config and writes a generated module.

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

If the config file is named callsheet.config.ts and lives at the project root, the --config flag is optional.

Flag	Description
`-c, --config <path>`	Path to the config file
`-h, --help`	Show help output

Using Callsheet with GraphQL for GraphQL setup walkthrough
Using Callsheet with ts-rest for ts-rest setup walkthrough
Working with Mixed Sources for combining multiple sources
Packages and Imports for package roles

Codegen Config