grats

library0.0.36jsnpmunverified

Grats provides an implementation-first, code-first approach to building GraphQL servers in TypeScript, enabling developers to define their GraphQL schema directly from their existing TypeScript types and functions using JSDoc-style annotations. This library leverages static analysis of your TypeScript code to automatically generate an executable GraphQL schema, eliminating the need for schema duplication or synchronization between SDL and resolver implementations. The current stable version, 0.0.36, reflects its active development phase, with frequent iterative updates and potentially breaking changes in minor `0.0.x` increments. Key differentiators include zero runtime overhead as the schema is extracted at build time, and a developer experience focused on reducing mental overhead by making the TypeScript implementation the single source of truth for the GraphQL schema, similar to approaches seen in Python (Strawberry) or C# (Hot Chocolate) but adapted for TypeScript's static nature.

web-framework serialization

npm install grats

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRATS

grats

web-frameworkjavascriptv0.0.36

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GqlInfo

✓ import { GqlInfo } from 'grats';

✗ const GqlInfo = require('grats');

Required for typing the `info` argument in resolvers, introduced in v0.0.27. As of v0.0.36, Grats is an ES Module, so `require()` will not work.

schema

✓ import { schema } from './schema.js';

Grats generates a `schema.ts` (or `schema.js`) file that exports the executable GraphQL schema. This is the primary symbol consumers import after running the `npx grats` CLI command. The `.js` extension is important for ESM environments.

@gqlType, @gqlField, @gqlQueryField, @gqlContext

✓ /** @gqlType */ class User {}

✗ import { gqlType } from 'grats'; // This is incorrect. @gqlType class User {}

Grats uses JSDoc-style docblock tags (e.g., `/** @gqlType */`) for schema declarations, not actual TypeScript decorators or imported symbols. These are processed by the Grats CLI at build time, not runtime.

This quickstart demonstrates setting up a basic Grats project with `graphql-yoga`. It defines a `User` type and `Context` using docblock annotations, generates the schema, and runs a GraphQL server.

/* package.json */ { "name": "grats-example", "version": "1.0.0", "description": "Grats GraphQL Quickstart", "main": "dist/server.js", "type": "module", "scripts": { "grats": "npx grats", "build": "npm run grats && tsc", "start": "npm run build && node dist/server.js" }, "keywords": [], "author": "", "license": "ISC", "devDependencies": { "@types/node": "^20.0.0", "grats": "^0.0.36", "typescript": "^5.5.0" }, "dependencies": { "graphql": "^16.0.0", "graphql-yoga": "^5.0.0" } } /* tsconfig.json */ { "compilerOptions": { "target": "es2022", "module": "esnext", "moduleResolution": "bundler", "esModuleInterop": true, "forceConsistentCasingInFileNames": true, "strict": true, "skipLibCheck": true, "outDir": "./dist", "resolveJsonModule": true, // Required for Grats to process JSDoc tags "jsx": "react-jsx", // or other if needed "strictPropertyInitialization": false // Often helpful with classes and Grats }, "include": ["src/**/*.ts"], "exclude": ["node_modules"] } /* src/user.ts */ /** * Represents a user in the system. * @gqlType */ export class User { /** @gqlField */ id: string; /** @gqlField */ name: string; constructor(id: string, name: string) { this.id = id; this.name = name; } /** * Returns a greeting for the user. * @gqlField */ greeting(salutation: string): string { return `${salutation}, ${this.name}!`; } } /* src/schema.ts */ // This file is generated by `npx grats` // It will contain the executable schema. /* src/server.ts */ import { createYoga } from 'graphql-yoga'; import { createServer } from 'node:http'; import { schema } from './schema.js'; // This file will be generated by Grats interface MyContext { viewerId: string | null; } /** @gqlContext */ class Context implements MyContext { constructor(request: Request) { // Simulate authentication this.viewerId = request.headers.get('x-viewer-id') || null; } } const yoga = createYoga<MyContext>({ schema, context: (request) => new Context(request.request) }); const server = createServer(yoga); server.listen(4000, () => { console.info('Server is running on http://localhost:4000/graphql'); console.info('Try a query like: { me { id name greeting(salutation: "Hello") } }'); });

grats --version

Debug

Known issues

breakingGrats v0.0.36 and later are published as ES Modules only. If you were using `require()` for Grats imports, you must migrate to ES `import` statements and ensure your project is configured for ESM.

fix

Set `"type": "module"` in your `package.json` and update all Grats-related imports from `require()` to `import`. Adjust `tsconfig.json`'s `module` and `moduleResolution` to `esnext` or `nodenext` respectively.

affects: >=0.0.36

breakingSince Grats v0.0.27, any type or class intended to be used as a GraphQL context object MUST be explicitly annotated with `/** @gqlContext */`. Resolvers accessing the GraphQL `info` object must explicitly type it using `GqlInfo` imported from `grats`.

fix

Add `/** @gqlContext */` to your context type definition. If using the `info` argument in a resolver, add `import { GqlInfo } from 'grats';` and type the argument as `info: GqlInfo`.

affects: >=0.0.27

breakingStarting with v0.0.34, the `getSchema` function (implicitly generated by Grats) now requires a configuration object. This is especially relevant if you are using custom scalars and need to provide serialization/parsing functions for them.

fix

Ensure that the call to the generated `getSchema` function in your server setup (often found in `schema.ts`) includes a configuration object, especially if you define custom scalars. Consult the Grats documentation for detailed custom scalar configuration.

affects: >=0.0.34

gotchaGrats infers schema definitions from JSDoc-style docblock tags (e.g., `/** @gqlType */`). These are compile-time annotations, not runtime decorators or imported symbols. Attempting to `import { gqlType } from 'grats'` or use `@gqlType` as a TypeScript decorator will result in errors.

fix

Always use `/** @tagName */` in JSDoc comments preceding the relevant TypeScript class, type, or function. Do not attempt to import these as runtime constructs.

affects: All

gotchaGrats has known limitations regarding complex TypeScript patterns. It may not correctly infer types or arguments for method wrappers, or support descriptions/deprecated tags on GraphQL enum values defined as TypeScript union types.

fix

Refer to the 'Limitations of Grats' documentation. Avoid wrapping methods in functions that obscure their type signatures. For enums, consider using TypeScript `enum`s or direct GraphQL SDL if these features are critical.

affects: All

gotchaGrats requires TypeScript `>=5.5` as a peer dependency. Using an older version of TypeScript in your project may lead to build failures or unexpected behavior when running `npx grats`.

fix

Ensure your project's `typescript` dependency in `package.json` meets the `>=5.5` requirement. Upgrade TypeScript if necessary.

affects: >=0.0.36

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module ... Not compatible with CommonJS 'require'.

Attempting to `require()` Grats or its generated output when Grats v0.0.36+ is an ES Module, or your project's `package.json` is not configured for ESM.

fix

Update `package.json` to include `"type": "module"`. Change all `require()` statements to `import` statements. Ensure `tsconfig.json` has `"module": "esnext"` and `"moduleResolution": "bundler"` or `"nodenext"`.

Grats encountered an error: The declaration of the type/class you use as your GraphQL context must now be annotated with @gqlContext

After Grats v0.0.27, the GraphQL context type/class is missing the `/** @gqlContext */` docblock tag.

fix

Add the `/** @gqlContext */` JSDoc comment immediately preceding your TypeScript class or type definition that serves as the GraphQL context.

Grats encountered an error: Type 'X' is not visible in the generated schema. Ensure it is exported from a module Grats knows about.

A GraphQL type, field, or query field defined with Grats annotations is not exported from its TypeScript module, making it inaccessible for schema generation.

fix

Ensure that any class, type, or function annotated with `/** @gqlType */`, `/** @gqlField */`, `/** @gqlQueryField */`, etc., is explicitly exported using `export` (e.g., `export class MyType { ... }`).

Grats encountered an error: Custom scalar 'X' has no serializer defined in the Grats configuration.

After Grats v0.0.34, custom scalars require explicit serialization/parsing functions provided in the configuration object passed to `getSchema`.

fix

Update the Grats configuration object in your generated `schema.ts` (or equivalent) to include `scalarSerializers` for each custom scalar you've defined, providing `serialize`, `parseValue`, and `parseLiteral` functions.

Upgrade

Version history

0.0.36latest on npm

Audit

Dependencies

typescriptrequiredRequired as a peer dependency for static analysis and schema generation. Grats typically requires TypeScript >=5.5.

graphqlrequiredThe generated schema is a standard graphql-js GraphQLSchema object, making this an implicit runtime dependency for any GraphQL server.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/captbaritone/grats ↗

packagehttps://www.npmjs.com/package/grats ↗

homepagehttps://grats.vercel.app ↗