Skip to main content

Welcome to Grats

What if building a GraphQL server were as simple as just writing functions?

When you write your GraphQL server in TypeScript, your fields and resovlers are already annotated with type information. Grats leverages your existing type annotations to automatically 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 valiating that your implementiaton 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 relevent type information.