graphql-let - A Webpack loader for GraphQL Code Generator

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.