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.
Top comments (0)