Skip to main content


Grats's interface is a command-line utility for extracting your project's GraphQL schema. It aims to be user friendly and helpful! You should expect the Grats CLI to give helpful error messages which guide you to a solution

Grats gets it's configuration options from your project's tsconfig.json file. By default Grats uses the TypeScript's own algorithm for locating your project's tsconfig.json. However, if you wish to use a different tsconfig.json file, you can specify it with the --tsconfig option.


For guidance on how to make Grats easy run in your project see Workflows.

Build (default command)

Grats' default command (build) creates a TypeScript module containing an executable GraphQL schema and a .graphql file containing the schema text. By default it places these files adjacent to your tsconfig.json file. If you wish to place them elsewhere, you can configure this in your tsconfig.json file.

npx grats

Or, if you want to leave Grats running while you work, you can use the --watch option.

npx grats --watch


Usage: grats [options] [command]

Extract GraphQL schema from your TypeScript project

-V, --version output the version number
--tsconfig <TSCONFIG> Path to tsconfig.json. Defaults to auto-detecting based on the current working directory
--watch Watch for changes and rebuild schema files as needed
-h, --help display help for command

locate [options] <ENTITY>


The locate command reports the location (file, line, column) at which a given type or field is defined in your code. grats locate can also be invoked by other tools. For example the click-to-definition feature of an GraphQL editor integration could use invoke this command to find the location of a type or field.

For example, Relay's VSCode Extension is exploring adding the ability to leverage such a tool.

# Locate a field
npx grats locate

# Locate a named type
npx grats locate User


Usage: grats locate [options] <ENTITY>

ENTITY GraphQL entity to locate. E.g. `User` or ``

--tsconfig <TSCONFIG> Path to tsconfig.json. Defaults to auto-detecting based on the current working directory
-h, --help display help for command