grats

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. Use when this capability is needed.
metadata	{"author":"captbaritone"}

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 — 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.
• Root types are auto-created. @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.
• Generics are supported. Connection<User> auto-materializes as UserConnection in the schema. See node_modules/grats/llm-docs/guides/generics.md.
• Derived context values enable dependency injection: a function annotated with @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.

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.