This document includes some advice on how to setup your project and processes to make the most of Grats.
Make it easy to run Grats
We recommend that you add a
grats script to your project's
This way any contributor can regenerate the schema by running
npm run grats.
You can pass additional arguments to Grats by adding them after
--. For example:
npm run grats -- --watch
Check in your schema
We recommend that you include Grats' generated GraphQL and TypeScript schemas in your repository. This approach has several advantages:
- You can easily see the changes to your schema during code reviews.
- Manually inspecting the schema is as simple as opening a file.
- Other tools, such as GraphiQL, client codegen, and editor integrations can easily access the schema.
- Allows other code tools to see that your GraphQL code is used (not "dead code").
Managing autoformatting and generated files
We recommend that you disable autoformatting for the generated files. For example by adding the generated file paths to your
.prettierignore file. Note that these paths will be different if you've changed their location in your Grats configuration.
If you do wish to keep them formatted, we recommend that you apply that formatting as part of your
grats npm script command:
"grats": "grats && prettier --write schema.graphql schema.ts"
To ensure that your code base does not get into a state where Grats cannot extract types due to errors, and that your schema file always matches your implementation, we recommend that you add a CI step that runs Grats and ensures that the schema matches the checked-in version.
Here's what an example script might look like:
# Exit if any command fails
# Run Grats
npm run grats
# Check that it didn't change anything
if [ -n "$(git status --porcelain)" ]; then
echo "Schema file is out of date. Please run 'npm run grats' and commit the changes."