graphql-let
A webpack loader to import type-protected codegen results directly from GraphQL documents.
Last updated a month ago by piglovesyou .
MIT · Repository · Original npm · Tarball · package.json
$ cnpm install graphql-let 
SYNC missed versions from official npm registry.

graphql-let npm version

A webpack loader to import type-protected codegen results directly from GraphQL documents.

Try the Next.js example that integrates graphql-let.

Why it exists

One of the strengths of GraphQL is enforcing data types on runtime. Further, TypeScript and GraphQL Code Generator (graphql-codegen) make it safer by typing data statically, so you can write truly type-protected code with rich IDE assists.

To enhance the development pattern, it's necessary to focus on a more specific use-case than what graphql-codegen allows; binding TypeScript (and assuming the use of Apollo-Client and React). In the way, graphql-let behaves as a subset of graphql-codegen.

graphql-let lets you import graphql-codegen results directly per GraphQL documents with TypeScript type definitions by webpack Loader power.

import { useNewsQuery } from './news.graphql'

const News: React.FC = () => {
	// Typed already️⚡️
	const { data: { news } } = useNewsQuery()
	if (news) return <div>{news.map(...)}</div>
}

How it works

Two things:

  • It runs graphql-codegen inside according to the .graphql-let.yml and pass the generated TypeScript source to the next loader.
  • It generates a file .d.ts.

You may also want only .d.ts before a webpack build to check types. Run graphql-let command to get .d.ts without running webpack.

Get started

This is an example of TypeScript + React + Apollo Client. Please replace the corresponding lines depending on your needs.

1. Install dependencies

Note graphql-let is devDependencies.

npm install -D graphql-let @graphql-codegen/cli @graphql-codegen/plugin-helpers @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo
npm install @apollo/react-common @apollo/react-components @apollo/react-hooks

2. Configure

.graphql-let.yml

Run this command to have a configuration template.

npx graphql-let init
# This will generate .graphql-let.yml

Next add graphql-codegen plugins in it. Please note that you have to generate TypeScript source by the plugins.

Edit it like this:

 schema: **/*.graphqls
 documents: **/*.graphql
 plugins:
   - typescript
+  - typescript-operations
+  - typescript-react-apollo

Available options:

property required type meaning examples
schema ✔︎ string The GraphQL schema info that graphql-let requests introspection to.
  • http://localhost:3000/graphql
  • schema.json
  • schema.graphqls
  • graphql/**/*.graphqls
All available formats
documents ✔︎ string \| string[] The GraphQL documents info of quereis and mutations etc. All the documents have to be separate files. ./queries-and-mutations/**/*.graphql
plugins ✔︎ string[] The plugin names of graphql-codegen.
  • typescript-operations
  • typescript-react-apollo
All available plugins
respectGitIgnore ✔︎ boolean Whether to use .gitignore to ignore like node_modules. It's passed to globby internally. true
config Record<string, boolean \| string> The configuration for the plugins. more info These are configured by default.
  • withHOC: false
  • withHooks: true

.gitignore

graphql-let will generate .d.ts files in the same folder of .graphql
and .graphqls. Add these line in your .gitignore.

+*.graphql.d.ts
+*.graphqls.d.ts

webpack.config.ts

The webpack loader also needs to be configured. Note that the content graphql-let/loader generates is JSX-TypeScript. You have to compile it to JavaScript with an additional loader such as babel-loader.

 const config: Configuration = {
   module: {
     rules: [
+      {
+        test: /\.graphql$/,
+        use: [
+          { loader: 'babel-loader', options: { presets: ['@babel/preset-typescript', '@babel/preset-react'] } },
+          { loader: 'graphql-let/loader' },
+        ]
+      }
     ]
   }
 }

3. Generate type declarations

Run this to generate .d.ts.

npx graphql-let

# This will generate files such as:
#   - src/query.graphql.d.ts
#   - src/schema.graphqls.d.ts

You may want to run it everytime calling tsc. Please check your package.json and modify like this.

   "scripts": {
-     "build": "tsc"
+     "build": "graphql-let && tsc"
   },

4. Code more

Enjoy HMR (Hot Module Replacement) of webpack with the generated
react-apollo hooks and IDE code assists.

import { useNewsQuery } from './news.graphql'

const News: React.FC = () => {
    // Already typed⚡️
    const { data: { news } } = useNewsQuery()
    if (news) return <div>{ news.map(...) }</div>
}

Experimental feature: Resolver Types

If you:

, graphql-let will generate .graphqls.d.ts to help you type GraphQL resolvers. Run:

yarn add -D @graphql-codegen/typescript-resolvers

yarn graphql-let

then you will get Resolver type from any GraphQL schema files you have.

import { Resolvers } from "./type-defs.graphqls";

const resolvers: Resolvers = {
  Query: {
    // All typed⚡️
    viewer(parent, args, context, info) {
      return { ... }
    },
  }
};

export default resolvers;

graphql-let/schema/loader is also available. It just pass GraphQL Content to the next loader but it generates resolver types in HMR. Set it up like this:

 const config: Configuration = {
   module: {
     rules: [
+      {
+        test: /\.graphqls$/,
+        use: [
+          { loader: 'graphql-tag/loader' },
+          { loader: 'graphql-let/schema/loader' },
+        ]
+      }
     ]
   }
 }

FAQ

So, it's just a graphql-codegen wrapper generating d.ts...?

Yes.

Is this a tool only for React?

No. There are more plugins that also generates .ts from GraphQL documents.

Can I write GraphQL documents in my .tsx as const query = gql`query News{ ... }`;?

Afraid not. You need to have separate files to execute the webpack loader. Besides, typing the value of gql`...` would be impossible.

What's the extension .graphqls? Should I use it for schema and .graphql for documents?

Not exactly, but I'd recommend them. I think using different extensions for schema/documents leads to a more understandable configuration for webpack loaders with fewer pitfalls. Another reason for .graphqls is that it's one of the supported extensions in the internal library.

How to integrate Apollo refetchQueries?

Query document exports DocumentNode named ${QueryName}Document that you can make use of it.

How to import another file for GraphQL Fragment?

You can't yet. Please watch the progress.

License

MIT

Current Tags

  • 0.9.0-beta.0                                ...           beta (4 months ago)
  • 0.10.0-canary.1                                ...           canary (a month ago)
  • 0.10.0                                ...           latest (a month ago)

36 Versions

  • 0.10.0                                ...           a month ago
  • 0.9.6                                ...           a month ago
  • 0.10.0-canary.1                                ...           a month ago
  • 0.9.5                                ...           2 months ago
  • 0.9.4                                ...           2 months ago
  • 0.9.3                                ...           3 months ago
  • 0.9.2                                ...           3 months ago
  • 0.9.0                                ...           3 months ago
  • 0.8.1                                ...           3 months ago
  • 0.9.0-beta.0                                ...           4 months ago
  • 0.8.0                                ...           4 months ago
  • 0.8.0-beta.3                                ...           4 months ago
  • 0.8.0-beta.2                                ...           4 months ago
  • 0.8.0-beta.1                                ...           4 months ago
  • 0.8.0-beta.0                                ...           4 months ago
  • 0.7.0                                ...           4 months ago
  • 0.7.0-0                                ...           4 months ago
  • 0.6.2                                ...           4 months ago
  • 0.6.1                                ...           4 months ago
  • 0.6.0                                ...           4 months ago
  • 0.5.2                                ...           4 months ago
  • 0.5.1                                ...           5 months ago
  • 0.5.0                                ...           5 months ago
  • 0.4.0                                ...           5 months ago
  • 0.3.5                                ...           5 months ago
  • 0.3.4                                ...           5 months ago
  • 0.3.3                                ...           5 months ago
  • 0.3.2                                ...           5 months ago
  • 0.3.1                                ...           5 months ago
  • 0.3.0                                ...           5 months ago
  • 0.2.4                                ...           6 months ago
  • 0.2.3                                ...           6 months ago
  • 0.2.2                                ...           6 months ago
  • 0.2.1                                ...           6 months ago
  • 0.2.0                                ...           6 months ago
  • 0.1.0                                ...           6 months ago
Maintainers (1)
Downloads
Today 1
This Week 9
This Month 9
Last Day 0
Last Week 12
Last Month 44
Dependencies (8)
Dependents (0)
None

Copyright 2014 - 2016 © taobao.org |