Skip to main content

Welcome to Grats

What if buildng a GraphQL server were as simple as adding annotations to your TypeScript code?

When you write your GraphQL server in TypeScript, your fields and resolvers are already annotated with type information. Grats leverages your existing type annotations to extract an executable GraphQL schema from your generic TypeScript resolver code.

By making your TypeScript implementation and its types the source of truth, you never have to worry about validating that your implementation matches your schema. Your implementation is your schema!

Examples​

Grats is flexible enough to work with both class-based and functional approaches to authoring GraphQL types and resolvers.

/** @gqlType */
type Query = unknown;

/** @gqlField */
export function me(_: Query): User {
  return new User();
}

/**
 * @gqlField
 * @deprecated Please use `me` instead. */
export function viewer(_: Query): User {
  return new User();
}

/**
 * A user in our kick-ass system!
 * @gqlType */
class User {
  /** @gqlField */
  name: string = "Alice";

  /** @gqlField */
  greeting(args: { salutation: string }): string {
    return `${args.salutation}, ${this.name}`;
  }
}

Output​

Both of the above examples define the following GraphQL schema:

type Query {
  me: User
  viewer: User @deprecated(reason: "Please use `me` instead.")
}

"""
A user in our kick-ass system!
"""
type User {
  name: String
  greeting(salutation: String!): String
}

How it works​

Grats works as a build step which statically analyzes your TypeScript code and generates a TypeScript module defining an executable schema. It also creates a .graphql schema file which can be used by clients and other tools.

To tell Grats which parts of your code to expose in the schema, simply annotate them with docblock tags like /** @gqlField */. Grats will scan your code for these tags and use them to automatically build your schema.

tip

Docblock tags generally correspond one-to-one with GraphQL schema constructs. You should be able to intuitively add Grats annotations to your code without having to learn a new DSL. If you guess wrong, Grats will let you know with a helpful error message.

For example, in some cases Grats may prompt you to use more explicit type annotations to ensure that it can "see" all the relevant type information.