tomevault-io Grats
Grats extracts a GraphQL schema from TypeScript code. Instead of writing a separate schema file, you annotate your TypeScript types and functions with docblock tags like /** @gqlType */ and /** @gqlField */. Grats then generates an executable GraphQL schema and a .graphql file as a build step.
Documentation
Grats ships comprehensive documentation in its npm package at node_modules/grats/llm-docs/. Read these files for detailed reference:
- Getting started:
node_modules/grats/llm-docs/getting-started/quick-start.md - All docblock tags:
node_modules/grats/llm-docs/docblock-tags.md - Resolver patterns:
node_modules/grats/llm-docs/resolvers.md - Configuration:
node_modules/grats/llm-docs/getting-started/configuration.md - CLI usage:
node_modules/grats/llm-docs/getting-started/cli.md
How to Write Grats Code
Write idiomatic TypeScript — classes, type aliases, interfaces, functions — whatever style suits the project. Then add docblock tags (/** @gqlType */, /** @gqlField */, etc.) to the constructs you want to expose in the GraphQL schema. Grats infers the GraphQL meaning from your TypeScript types. If something is ambiguous or incorrect, Grats will give you a helpful error message telling you how to fix it.
You do not need to learn a specific pattern or DSL. Just write the TypeScript code that feels natural and annotate it. Grats supports classes, interfaces, type aliases, functions, static methods, and more — use whatever fits.
Annotate the project's existing model types and data classes directly rather than creating a separate "resolver" layer with new wrapper types. Grats is designed to work with your real domain types — add @gqlType and @gqlField to the types you already have.
Docblock Tags
Each tag maps directly to a GraphQL schema construct. Tags must use /** (two asterisks).
| Tag | Purpose |
|---|---|
@gqlType |
Define a GraphQL object type |
@gqlField |
Define a field on a type |
@gqlQueryField |
Define a field on the root Query type |
@gqlMutationField |
Define a field on the root Mutation type |
@gqlSubscriptionField |
Define a field on the root Subscription type |
@gqlInterface |
Define a GraphQL interface |
@gqlUnion |
Define a GraphQL union |
@gqlEnum |
Define a GraphQL enum |
@gqlScalar |
Define a custom GraphQL scalar |
@gqlInput |
Define a GraphQL input type |
@gqlContext |
Mark a type as the GraphQL context object |
For detailed documentation on each tag, read the files in node_modules/grats/llm-docs/docblock-tags/.
Configuration
Grats is configured under the "grats" key in tsconfig.json:
{
"grats": {
"nullableByDefault": true,
"importModuleSpecifierEnding": ".js"
}
}
For all options, read node_modules/grats/llm-docs/getting-started/configuration.md.
Running Grats
npx grats # Generate schema
npx grats --watch # Watch mode
npx grats --fix # Auto-fix common issues
Rerun Grats after any change that is expected to modify the GraphQL schema (adding or changing types, fields, arguments, etc.) to regenerate the schema files.
The project may have its own script or workflow for running Grats (e.g., an npm script, a build step, or a watch task). Check the project's package.json scripts and documentation first, and defer to the project's approach if one exists.
Working with Generated Files
Grats generates schema.ts and schema.graphql. These files should be committed to the repository — they are expected to be checked in so that schema changes are visible in code review and accessible to other tools. Do not add them to .gitignore.
Do not manually edit generated files or run autoformatters on them. If CI fails with a "schema out of date" error, rerun Grats and commit the updated files.
For more details, read node_modules/grats/llm-docs/guides/workflows.md.
Things You Might Not Expect
- All fields are nullable by default per GraphQL best practices —
stringproducesString, notString!. Prefer keeping fields nullable.@killsParentOnExceptioncan make a field non-null, but use it with caution: if the resolver throws, the error propagates up and nulls out the nearest nullable parent, increasing the blast radius. For projects that want clients to see which fields are expected to be non-null absent errors, enablestrictSemanticNullabilityin the Grats config. Seenode_modules/grats/llm-docs/resolvers/nullability.mdandnode_modules/grats/llm-docs/guides/strict-semantic-nullability.md. - Root types are auto-created.
@gqlQueryFieldautomatically creates theQuerytype — you don't need to define it separately. Seenode_modules/grats/llm-docs/docblock-tags/root-fields.md. @deprecatedJSDoc tag auto-maps to the GraphQL@deprecateddirective. No need for@gqlAnnotate. Seenode_modules/grats/llm-docs/resolvers/deprecated.md.- Generics are supported.
Connection<User>auto-materializes asUserConnectionin the schema. Seenode_modules/grats/llm-docs/guides/generics.md. - Derived context values enable dependency injection: a function annotated with
@gqlContextthat takes the root context and returns a new type creates an injectable value. Seenode_modules/grats/llm-docs/docblock-tags/context.md.
Additional Documentation
For advanced topics, read the files in node_modules/grats/llm-docs/:
- Guides:
guides/— subscriptions, dataloader, generics, incremental migration, workflows, permissions, connection spec - FAQ:
faq/— design principles, limitations, how Grats works - Examples:
examples/— Apollo Server, Yoga, Next.js, production app patterns
Source: captbaritone/grats — distributed by TomeVault.