// Build GraphQL servers by annotating TypeScript code with docblock tags like @gqlType and @gqlField. Use when writing, reviewing, or refactoring GraphQL resolvers in a project that uses Grats, or when the user mentions Grats, @gqlType, @gqlField, or similar docblock tags.
| name | grats |
| description | Build GraphQL servers by annotating TypeScript code with docblock tags like @gqlType and @gqlField. Use when writing, reviewing, or refactoring GraphQL resolvers in a project that uses Grats, or when the user mentions Grats, @gqlType, @gqlField, or similar docblock tags. |
| license | MIT |
| metadata | {"author":"grats","version":"1.0.0"} |
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.
Grats ships comprehensive documentation in its npm package at node_modules/grats/llm-docs/. Read these files for detailed reference:
node_modules/grats/llm-docs/getting-started/quick-start.mdnode_modules/grats/llm-docs/docblock-tags.mdnode_modules/grats/llm-docs/resolvers.mdnode_modules/grats/llm-docs/getting-started/configuration.mdnode_modules/grats/llm-docs/getting-started/cli.mdWrite 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.
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/.
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.
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.
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.
string produces String, not String!. Prefer keeping fields nullable. @killsParentOnException can 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, enable strictSemanticNullability in the Grats config. See node_modules/grats/llm-docs/resolvers/nullability.md and node_modules/grats/llm-docs/guides/strict-semantic-nullability.md.@gqlQueryField automatically creates the Query type — you don't need to define it separately. See node_modules/grats/llm-docs/docblock-tags/root-fields.md.@deprecated JSDoc tag auto-maps to the GraphQL @deprecated directive. No need for @gqlAnnotate. See node_modules/grats/llm-docs/resolvers/deprecated.md.Connection<User> auto-materializes as UserConnection in the schema. See node_modules/grats/llm-docs/guides/generics.md.@gqlContext that takes the root context and returns a new type creates an injectable value. See node_modules/grats/llm-docs/docblock-tags/context.md.For advanced topics, read the files in node_modules/grats/llm-docs/:
guides/ — subscriptions, dataloader, generics, incremental migration, workflows, permissions, connection specfaq/ — design principles, limitations, how Grats worksexamples/ — Apollo Server, Yoga, Next.js, production app patterns