Registry / devops / typed-graphql-builder

typed-graphql-builder

library5.1.2jsnpmunverified

A GraphQL query builder v5.1.2 that replaces string-based `gql` queries or `.graphql` files with pure TypeScript code generation. It generates `TypedDocumentNode` objects compatible with Apollo Client, Urql, graphql-request, and any other library supporting `TypedDocumentNode`. Unlike code-first approaches like GraphQL Code Generator, this library provides a fully typed builder API that reduces boilerplate and catches errors at compile time. The generated API uses a functional, composable syntax with automatic variable type inference via the `$` and `$$` helpers. Released under MIT, updated frequently with breaking changes in major versions.

devops

npm install typed-graphql-builder

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TYPED-GRAPHQL-BUIL

typed-graphql-builder

devopsjavascriptv5.1.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

query

✓ import { query } from './generated-api'

✗ import { query } from 'typed-graphql-builder'

The `query`, `mutation`, and `subscription` functions are exported from the generated file, not the library itself.

✓ import { $ } from './generated-api'

✗ import $ from './generated-api'

`$` is a named export, not default. It is used to define input variables.

TypedDocumentNode

✓ import type { TypedDocumentNode } from '@graphql-typed-document-node/core'

✗ import { TypedDocumentNode } from './generated-api'

Type import from the peer dependency, not from the generated API.

Generates a typed query from a GraphQL schema and uses it with Apollo Client's useQuery hook.

// 1. Generate the API from a schema // npx typed-graphql-builder --schema https://countries.trevorblades.com --output generated-api.ts // 2. Install peer dependencies // npm install @graphql-typed-document-node/core graphql-tag // 3. Write a query import { query, $ } from './generated-api'; import { useQuery } from '@apollo/client'; const continentQuery = query((q) => [ q.continents((c) => [c.name, c.code]), ]); // ContinentQuery is TypedDocumentNode<{continents: {name: string, code: string}[]}, {}> // With variables const countryQuery = query((q) => [ q.countries( { filter: { continent: { eq: $('continentCode') } } }, (c) => [c.code, c.capital, c.name] ), ]); // Use with Apollo const MyComponent = () => { const { data } = useQuery(continentQuery); return <div>{data?.continents.map(c => c.name)}</div>; };

Debug

Known issues

breakingv5 drops support for Node.js < 18 and changes the generated API's import paths.

fix

Upgrade Node.js to 18+ and regenerate the API with npx typed-graphql-builder.

affects: >=5.0.0 <6.0.0

deprecatedThe old `gql` string builder (used in v3) is removed; must switch to new builder syntax.

fix

Migrate to the builder pattern as shown in the documentation.

affects: >=4.0.0

gotchaThe `$` helper allows null by default; use `$$` to require non-null.

fix

Use `$$('varName')` when the variable must be non-null.

affects: >=4.0.0

breakingv4 changed the generated output from functions like `gql` to `query`, `mutation`, `subscription` exports.

fix

Regenerate API with v4 CLI and update imports to use `query` from './generated-api'.

affects: >=4.0.0 <5.0.0

Errors

Common errors & fixes

Cannot find module './generated-api' or its corresponding type declarations.

The generated file does not exist or was not regenerated after schema changes.

fix

Run `npx typed-graphql-builder --schema <schema> --output generated-api.ts` and ensure the output file is included in your project.

Module '"@graphql-typed-document-node/core"' does not have a default export.

Incorrect import of TypedDocumentNode; trying to import default instead of named.

fix

Use `import type { TypedDocumentNode } from '@graphql-typed-document-node/core'`.

Argument of type '...' is not assignable to parameter of type 'never'.

Using the builder incorrectly, e.g., missing a callback or providing wrong field.

fix

Check the schema fields and the builder signature: each selection must be inside a callback that returns an array of selected fields.

Type 'undefined' is not assignable to type 'string'.

The `$` helper produced a nullable variable; the consumer expects non-null.

fix

Use `$$('varName')` to enforce non-null or add a check at consumption.

Upgrade

Version history

5.1.2latest on npm

Audit

Dependencies

@graphql-typed-document-node/corerequiredRequired for TypedDocumentNode type definitions; a peer dependency of the generated code.

graphql-tagrequiredRequired for compiling GraphQL strings; a peer dependency of the generated code.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/typed-graphql-builder/typed-graphql-builder ↗

packagetyped-graphql-builder ↗

homepagehttps://github.com/typed-graphql-builder/typed-graphql-builder#readme ↗