graphql-let

0.18.6 verified Sat Apr 25 auth: no javascript

A webpack loader, Babel plugin, Babel macro, and CLI tool that wraps GraphQL Code Generator to provide zero-config, typed GraphQL imports with HMR support. Current stable version is 0.18.6, released periodically. It automatically generates TypeScript types and runtime hooks from .graphql files or inline gql tags, integrating seamlessly with webpack, Next.js, and Create React App. Key differentiators include minimal configuration, built-in HMR, and support for multiple entry points (loader, macro, plugin). Requires peer dependencies: @graphql-codegen/cli, @graphql-codegen/import-types-preset, @graphql-codegen/typescript, graphql, and TypeScript.

Common errors

error You need to run graphql codegen first. Run `npx graphql-let` ↓

cause Generated files are missing; graphql-let requires running its CLI to generate types.

fix

Run npx graphql-let to generate the necessary TypeScript files.

error Cannot find module '@graphql-codegen/cli' ↓

cause Missing peer dependency @graphql-codegen/cli.

fix

Install the missing peer dependency: npm install --save-dev @graphql-codegen/cli.

error TypeError: Cannot read properties of undefined (reading 'kind') ↓

cause GraphQL schema or documents not found or malformed.

fix

Ensure schema and documents paths in .graphql-let.yml are correct and files exist.

error Module not found: Error: Can't resolve 'graphql-let/loader' ↓

cause graphql-let is not installed or the loader path is incorrect.

fix

Install graphql-let: npm install --save-dev graphql-let, and use the loader string 'graphql-let/loader'.

Warnings

breaking In v0.18.0, generated types were moved to a shared directory `graphql-let/__generated__/__types__`. Existing projects must update imports and regenerate. ↓

fix Regenerate with v0.18+ and adjust import paths to use the shared types.

deprecated The `gql` function from the main package is deprecated in favor of `graphql-let/macro` for babel-plugin-macros support. ↓

fix Use `import { gql, load } from 'graphql-let/macro'` instead.

gotcha graphql-let requires both `@graphql-codegen/cli` and its presets as peer dependencies; missing them causes cryptic errors during code generation. ↓

fix Install all peer dependencies: `npm install --save-dev @graphql-codegen/cli @graphql-codegen/import-types-preset @graphql-codegen/typescript`.

gotcha The `.graphql-let.yml` config file must be in the project root or specified via `configFile` in webpack loader options; otherwise graphql-let silently fails. ↓

fix Create `.graphql-let.yml` in the project root or pass `configFile: './path/to/.graphql-let.yml'` in the loader options.

deprecated Using `require('graphql-let/loader')` in CommonJS is deprecated; use ES import or webpack loader string. ↓

fix Use `{ test: /\.graphql$/, loader: 'graphql-let/loader' }` in webpack config.

Install

npm install graphql-let

yarn add graphql-let

pnpm add graphql-let

Imports

default (webpack loader)
wrong
```
import gql from 'graphql-let'
```
correct
```
// In webpack config: { test: /\.graphql$/, loader: 'graphql-let/loader' }
```
For webpack, use 'graphql-let/loader' as a loader, not a module import.
gql, load
wrong
```
import { gql } from 'graphql-let'
```
correct
```
import { gql, load } from 'graphql-let/macro'
```
The macro entrypoint is separate: 'graphql-let/macro'. Using 'graphql-let' directly is incorrect.
gql (Babel plugin)
wrong
```
import gql from 'graphql-let'
```
correct
```
import { gql } from 'graphql-let'
```
For Babel plugin, import the named export 'gql' from the main package.

Quickstart

Configures graphql-let with a YAML config, defines a GraphQL query, and uses the generated React hook in a component.

// .graphql-let.yml
schema: 'schema.graphql'
documents: 'src/**/*.graphql'
plugins:
  - '@graphql-codegen/typescript'
  - '@graphql-codegen/typescript-operations'
  - '@graphql-codegen/typescript-react-apollo'

// src/query.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
  }
}

// src/App.tsx
import React from 'react';
import { useGetUserQuery } from './query.graphql';

const App: React.FC = () => {
  const { data, loading, error } = useGetUserQuery({ variables: { id: '1' } });
  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  return <div>{data?.user.name}</div>;
};

export default App;