graphql-let - A Webpack loader for GraphQL Code Generator
Tags: graphql, codegen, webpack
Published: 2021-07-29 09:08:51

> This article was published on Wednesday, November 25, 2020 by [Soichi Takamura](https://twitter.com/piglovesyou1) @ [The Guild Blog](https://the-guild.dev/)

[`graphql-let`](https://github.com/piglovesyou/graphql-let) is a wrapper tool that makes using
GraphQL Code Generator smoother and easier. In this article, I'll explain what graphql-let is and
how it relates to GraphQL Code Generator.

## What Is `graphql-let`?

"It's a webpack loader" would be a simple explanation to start. It lets you directly import GraphQL
documents and use GraphQL Code Generator's result as below:

```tsx
// You can directly import typed objects generated by GraphQL code generator⚡️
import { useNewsQuery } from './news.graphql'

const News: React.FC = () => {
    // Yes, fetched data is typed too💪
    const { data: { news } } = useNewsQuery()
    if (news) return <div>{news.map(...)}</div>
}
```

The fastest way to try graphql-let is to use
[the Next.js example from their official repository](https://github.com/vercel/next.js/tree/canary/examples/with-typescript-graphql)
by hitting the following command.

```bash
yarn create next-app --example with-typescript-graphql with-typescript-graphql-app
```

`graphql-let` is made for enhancing the development pattern using **TypeScript and GraphQL**, the
most effective combination to solve many front-end problems in 2020. It heavily depends on GraphQL
Code Generator, so in other words, if you don't use any of TypeScript and GraphQL Code Generator,
you don't need `graphql-let` either.

graphql-let's configuration file, `.graphql-let.yml`, looks intentionally similar to `codegen.yml`
of GraphQL Codegen. Next, I'll explain what `graphql-let` does by calling GraphQL Code Generator's
API under the hood.

## What Does `graphq-let` Add on Top of GraphQL Code Generator API?

GraphQL Code Generator is an awesome tool. It's an infrastructure to expand the possibility of
GraphQL nowadays. graphql-let is in `devDependencies` as well as GraphQL Code Generator, so it does
nothing in runtime-level too. graphql-let eases two pain points while you develop using `codegen`
command of GraphQL Code Generator.

With GraphQL Code Generator,

*   You need to point to the output path as `import "../../../__generated__/out.tsx"` everywhere
*   You need to run the `graphql-codegen` command manually every time you change the single file

With `graphql-let`,

*   You can directly import GraphQL source as `import "./news.graphql"` thanks to the webpack power.
*   You can process codegen in HMR too, thanks to webpack again.
*   It achieved the above by getting rid of the `generates` option, where graphql-let takes care of
    generated paths and lets you forget them.

Please note that there are limitations, mainly because graphql-let controls output paths. I'd
recommend you
[read the documentation](https://github.com/piglovesyou/graphql-let/#configuration-is-compatible-with-codegenyml-except)
once to get the picture of how graphql-let and GraphQL Code Generator different.

## Other Features

There are other convenient features graphql-let provides to make it more practical.

### `#import` Syntax Support

`#import` is useful to share fragments of GraphQL document, especially when your project codebase
becomes big. If you have a fragment file named `partial.graphql` like this,

```graphql
fragment Partial on User {
  id
  name
}
```

you can share it from other places by importing it.

```graphql
# import Partial from './partial.graphql'
query Viewer {
  viewer {
    ...Partial
  }
}
```

### Jest Transformer

graphql-let exports `graphql-let/jestTransformer` that you can use in Jest testing. Please
[read the docs](https://github.com/piglovesyou/graphql-let/#jest-transformer) for more information.

### Babel Plugin for Inline GraphQL Documents

It's still partial support, but `graphql-let` provides a babel plugin to allows developers to write
inline GraphQL documents.

```ts
import gql from 'graphql-let'

// Typed️⚡️
const { useViewerQuery } = gql(`
    query Viewer {
        viewer { name }
    }
`)
```

It generates `.d.ts` files in `node_modules/@types/graphql-let` by default to apply overload
signatures on the function `gql`. Ideally, it should be available in both a babel plugin and the
webpack loader but there needs to be more effort.

## Why I Made `graphql-let`

I made this for front-end devs to adopt the TypeScript and GraphQL even more in their project😄

When I actively maintained
[kriasoft/react-starter-kit](https://github.com/kriasoft/react-starter-kit) a few years ago, I
realized it's so happy to use Apollo Server and Apollo Client. At the moment, though, Apollo
primarily supported HOCs instead of React Hooks, which leads to troublesome to match types of
GraphQL operations and fetched data manually. Then, `@graphql-codegen/typescript-react-apollo`
appeared and solved all the problems, except ones that graphql-let deals with later.

The less setup process GraphQL development requires, the more people can adopt GraphQL I believe,
simply because GraphQL itself solves many problems web development has been struggling with without
it for a decade. I couldn't be happier if a few of you get to know the power of GraphQL through
using graphql-let.