
For the last year I’ve been building [Grats](https://grats.capt.dev/) with the goal of demonstrating what I believe to be a fundamentally better developer experience for building GraphQL servers in TypeScript.

The idea is that you simply annotate your existing TypeScript code with docblocks to indicate which constructs you want to expose and let Grats leverage your code’s existing names and types to extract a fully type-safe, executable, GraphQL schema.

Let’s look at an example of a simple model that’s been annotated:

```tsx
/**
 * A user in our system
 * @gqlType
 */
type User = {
  /** @gqlField */
  name: string;
};

/** @gqlField */
export function greeting(user: User): string {
  return `Hello ${user.name}`;
}
```

From this, Grats derives this GraphQL schema:

```graphql
"""
A user in our system
"""
type User {
  name: String!
  greeting: String!
}
```

[_Playground link_](https://grats.capt.dev/playground/#N4IgJg9gxiBcIHoBUSAEAdAdqtBBVArgM4CmATqgJbYQEVECeRALiQLZY6oACA5gI4AbACoMADiU5IEWZuJKoAqqQoBeVME6pkaPkIBilEoLA4Z2VJgCGbErFQsy1XgG4sAXyxYdPAYMPGptJYJAAeYhBkzKgAZgSYUMyUENi8ZCQkSZi8ABTE5PbK5ACU9o7OGlrpzHTYAAYAEsaCEKgAJMD5ZAB01rbudW6Y7iAANCBQKTGUvHCgmASCglYARoIkAEIMACIkMVaLzHDMZAQk4+kRUaISAMpQTmLMNyQAomRkkUTHpyTu4wA3IwAdzmIFozDEBGYAHknslMHAQEQwIIxsiABYQYEAcTIVmYRG2lHSiUoAJI31g+0EpH+IAAaq8AEq3ACSMIAcnAAIzuIA)

Note that we didn’t have to explicitly declare any of the types or names that we wanted to appear in our schema. Grats simply derives them directly from our TypeScript code. People who have adopted Grats report that it makes the development of GraphQL servers feel more lightweight, and that much of the mental overhead of GraphQL seems to melt away.

## Bringing implementation-first development to TypeScript

This method of schema development, which I call [implementation-first](https://jordaneldredge.com/blog/implementation-first/), is not new in the GraphQL ecosystem. Python has [Strawberry](https://strawberry.rocks/), C# has [Hot Chocolate](https://chillicream.com/docs/hotchocolate/), and Rust has [Juniper](https://github.com/graphql-rust/juniper), and Meta's internal GraphQL server (written in Hack/PHP) [operates very similarly](https://youtu.be/G_zipR8Y8Ks?t=1159). However those tools all depend upon either runtime type introspection or compile-time macros, neither of which is possible in TypeScript.

Enabling implementation-first GraphQL for TypeScript requires a novel approach. Grats’ innovation is that it implements schema extraction using static analysis. Grats analyzes your code as a collection of [ASTs](https://en.wikipedia.org/wiki/Abstract_syntax_tree) and from that is able to infer your GraphQL schema.

## Pros

In addition to the improved developer experience, Grats has a number of other advantages relative to existing TypeScript offerings:

- **Automatic type safety** — Your TypeScript types _are_ your GraphQL types. No need to keep your schema declarations in sync with your implementation.
- **No runtime overhead** — Grats is a development-only build tool, it does not introduce any runtime overhead or increase bundle size. This can be especially impactful when used at the edge or in the browser.
- **Friendly error messages** — Instead of relying on sophisticated TypeScript types which often report verbose and cryptic errors, Grats has an exact understanding of each issue it reports and has customized and helpful error messages for each.
- **Encourages best practices** — Grats defaults to typing all fields as nullable, a [GraphQL best practice](https://graphql.org/learn/best-practices/#nullability) which helps enable more resilient responses.

## Cons

No solution is without tradeoffs. Here are some reasons why reasonable people might choose not to use Grats:

- **Grats introduces a build step** — Build steps introduce friction into your development process which must be weighed against the pros enumerated above.
- **No existing plugin ecosystem** — Well-established tools like [Pothos](https://pothos-graphql.dev/) come with an ecosystem of plugins which can provide significant value. Grats does not (yet?) have a comparable ecosystem.
- **Schema design is not forced** — Schema-first solutions provide a forcing function to explicitly and intentionally design your schema. With Grats, you must mentally design your schema as you implement it, and then confirm that design with the generated schema.

## Conclusion

Grats leverages a novel static analysis approach to enable a lighter weight and overall more pleasant developer experience for building GraphQL servers with TypeScript. If it sounds interesting to you, please check out the [Grats website](https://grats.capt.dev/). Some places to start might be:

- [Quick Start](https://grats.capt.dev/docs/getting-started/quick-start)
- [Playground](https://grats.capt.dev/playground)
- [Incremental Migration](https://grats.capt.dev/docs/guides/incremental-migration)
- [Design Principles](https://grats.capt.dev/docs/faq/design-principles)

If you have questions or comments I’d love to hear from you on [Twitter](https://twitter.com/captbaritone/), [Threads](https://www.threads.net/@captbaritone), or in the [Grats Discord server](https://discord.gg/xBf4gxPefu).

Bringing Implementation-First GraphQL to TypeScript via a novel static analysis approach.

Grats: A More Pleasant Way to Build TypeScript GraphQL Servers


# Welcome to My MDX Test Page

## Introduction

This is a paragraph with **bold** and *italic* text. You can also use [links](https://example.com) in your content.

### Lists

Here's an unordered list:

- Item 1
- Item 2
- Item 3

And an ordered list:

1. First item
2. Second item
3. Third item

### Blockquotes

> This is a blockquote. It can span multiple lines and is typically used for quoting external sources or highlighting important information.

### Code

Here's some inline `code` and a code block:

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
greet('World');
```




A comprehensive test of various markdown elements and custom MDX components

Notes

Grats: A More Pleasant Way to Build TypeScript GraphQL Servers

MDX Test Page 2

MDX Test Page 3