Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default (webpack loader)
✓ // In webpack config: { test: /\.graphql$/, loader: 'graphql-let/loader' }
✗ import gql from 'graphql-let'
For webpack, use 'graphql-let/loader' as a loader, not a module import.
gql, load
✓ import { gql, load } from 'graphql-let/macro'
✗ import { gql } from 'graphql-let'
The macro entrypoint is separate: 'graphql-let/macro'. Using 'graphql-let' directly is incorrect.
gql (Babel plugin)
✓ import { gql } from 'graphql-let'
✗ import gql from 'graphql-let'
For Babel plugin, import the named export 'gql' from the main package.
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;
graphql-let --version
Debug
Known issues
breakingIn v0.18.0, generated types were moved to a shared directory `graphql-let/__generated__/__types__`. Existing projects must update imports and regenerate.fixRegenerate with v0.18+ and adjust import paths to use the shared types.
affects: >=0.16.0 <0.18.0
deprecatedThe `gql` function from the main package is deprecated in favor of `graphql-let/macro` for babel-plugin-macros support.fixUse `import { gql, load } from 'graphql-let/macro'` instead. affects: >=0.17.0
gotchagraphql-let requires both `@graphql-codegen/cli` and its presets as peer dependencies; missing them causes cryptic errors during code generation.fixInstall all peer dependencies: `npm install --save-dev @graphql-codegen/cli @graphql-codegen/import-types-preset @graphql-codegen/typescript`.
affects: >=0.16.0
gotchaThe `.graphql-let.yml` config file must be in the project root or specified via `configFile` in webpack loader options; otherwise graphql-let silently fails.fixCreate `.graphql-let.yml` in the project root or pass `configFile: './path/to/.graphql-let.yml'` in the loader options.
affects: >=0.16.0
deprecatedUsing `require('graphql-let/loader')` in CommonJS is deprecated; use ES import or webpack loader string.fixUse `{ test: /\.graphql$/, loader: 'graphql-let/loader' }` in webpack config. affects: >=0.18.0
Errors
Common errors & fixes
You need to run graphql codegen first. Run `npx graphql-let`
Generated files are missing; graphql-let requires running its CLI to generate types.
fixRun `npx graphql-let` to generate the necessary TypeScript files.
Cannot find module '@graphql-codegen/cli'
Missing peer dependency @graphql-codegen/cli.
fixInstall the missing peer dependency: `npm install --save-dev @graphql-codegen/cli`.
TypeError: Cannot read properties of undefined (reading 'kind')
GraphQL schema or documents not found or malformed.
fixEnsure `schema` and `documents` paths in `.graphql-let.yml` are correct and files exist.
Module not found: Error: Can't resolve 'graphql-let/loader'
graphql-let is not installed or the loader path is incorrect.
fixInstall graphql-let: `npm install --save-dev graphql-let`, and use the loader string `'graphql-let/loader'`.
Audit
Dependencies
@graphql-codegen/clirequiredCore code generation engine
@graphql-codegen/import-types-presetrequiredRequired for import types preset
@graphql-codegen/typescriptrequiredTypeScript codegen plugin
graphqlrequiredRuntime dependency for GraphQL operations
typescriptrequiredTypeScript compiler for type generation