
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

MDX Test Page 2


It’s been quite the rollercoaster of a year so far. It’s had its fair share of good and bad moments. Usually, when I’m facing something negative, my first instinct is to look for ways to mitigate it or resolve it. This tendency can be frustrating because I struggle to focus on anything else until I devise a plan to address the situation. However, it has also helped me with a lot of things in life. I’d rather act this way than sit idle and procrastinate. I’m not saying that whatever I come up with always works out as planned; in fact, it rarely does, but it gives me a sense of satisfaction from acting on my “call to action.” It’s like a sudden boost of motivation after a period of gloom.

I feel odd saying this, but I generally feel more productive during and after phases of dejection. I’ve had quite a few of those this year, most of them concerning the same matters. While most things are manageable with this “call to action” mindset, it has an obvious flaw: it doesn’t account for things beyond one’s control. This is the part I’ve struggled with the most this year, but I’ve tried to make myself understand that sometimes you just need to embrace things as they are and learn from them. One way I’ve found to cope is by keeping myself busy or planning activities that create enough distraction in my brain to forget things that were bothering me. This blog is also a result of that.

I made this blog site in July after a slump—it took me about a week to get it up and running. Once it was done, I decided I’d try to jot down all these random thoughts I was feeling and thinking about. They weren’t even related to what I was going through—just completely random stuff I wanted to talk about with someone who had a better understanding of the topic. But every time I sat down to write, my thoughts just dissipated, leaving me completely blank. After multiple failed attempts at this, I decided that maybe it wasn’t for me. I thought to myself that I’ve never really been someone to preach about anything, and I didn’t see myself as someone who had anything worth reading about.

A few more weeks of feeling despondent, and I reached a point where I didn’t want to talk to or see anyone. I wanted to express myself, to talk—but every time I tried, I was at a loss for words, both in writing and conversation. I knew I had to change something, and finally, the “call to action” kicked in again. Earlier in the year, I went through a similar phase of dejection and considered taking time off work to travel, hoping it would help take my mind off things. When I looked into it, I found that my work had a policy allowing me to work internationally. I started looking into it, but the plan got dropped as I got distracted by other things.

This time around, I just wanted some quiet time away from family and everyone, so I thought of renting an apartment for a few months in the city. That way, I could get my act together without being questioned every day about why I looked so down. This option, as good as it was, turned out to be an expensive one. After a bit more brainstorming, I went back to my original plan from the start of the year and finally applied to work internationally. Since this was going to be my first time working internationally as well as traveling solo, I wanted to keep things somewhat familiar. I decided to pick Bali for the first four weeks and then Singapore for the final week. Planning this trip and thinking about it helped create the distraction I needed to take my mind off things. I had been to Bali and Singapore a few times before, which gave me some comfort as I had an idea of what to expect, but I wanted to do things I hadn’t done before and challenge myself in ways I usually wouldn’t.

For the next blog, I’ll be sharing my experiences in Bali and Singapore. Looking back, deciding to solo travel was one of the most important choices I made this year. It gave me a new way to release my emotions while growing and experiencing new things.


Blog

Grats: A More Pleasant Way to Build TypeScript GraphQL Servers

MDX Test Page 2

The Prologue