graphql-let - A Webpack loader for GraphQL Code Generator

This article was published on Wednesday, November 25, 2020 by Soichi Takamura @ The Guild Blog

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:

// 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
by hitting the following command.

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
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,

fragment Partial on User {
  id
  name
}

you can share it from other places by importing it.

# 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 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.

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 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.