Registry / development / gql-query-builder

gql-query-builder

library3.8.0jsnpmunverified

A simple JavaScript/TypeScript utility for building GraphQL queries, mutations, and subscriptions from plain JSON objects. Current stable version is 3.8.0, released under MIT license. Enables programmatic construction of GraphQL operations without string concatenation or template literals, supporting variables with required/type/list metadata, aliases, nested fields, operation names, and custom adapters. Ships TypeScript definitions and is compatible with both ESM and CommonJS. Minimal footprint with no runtime dependencies, making it suitable for server-side and client-side usage. Compared to alternatives like graphql-tag, it offers a simpler API focused on object composition rather than template parsing.

development

npm install gql-query-builder

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GQL-QUERY-BUILDER

gql-query-builder

developmentjavascriptv3.8.0

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.

default

✓ import gql from 'gql-query-builder'

✗ import * as gql from 'gql-query-builder'

Default export provides namespaced access to query, mutation, subscription functions. As of v3, the package has both named and default exports.

query

✓ import { query } from 'gql-query-builder'

✗ const query = require('gql-query-builder').query

Named import for individual functions. Works in both ESM and CJS environments.

mutation

✓ import { mutation, subscription } from 'gql-query-builder'

✗ import { mutation } from 'gql-query-builder'; import { subscription } from 'gql-query-builder'

Multiple named imports can be combined in one import statement.

Shows how to generate GraphQL query and mutation strings using JavaScript objects with variables and fields.

import { query, mutation } from 'gql-query-builder'; // Query example const q = query({ operation: 'getUser', fields: ['id', 'name', 'email'], variables: { id: { value: 1, required: true } } }); console.log(q); // Output: query getUser($id: String!) { getUser(id: $id) { id name email } } // Mutation example const m = mutation({ operation: 'createUser', fields: ['id', 'name'], variables: { name: { value: 'John', required: true, type: 'String' }, email: { value: 'john@example.com', required: true, type: 'String' } } }); console.log(m); // Output: mutation createUser($name: String!, $email: String!) { createUser(name: $name, email: $email) { id name } }

Debug

Known issues

gotchaVariables object structure changed in v3, with 'value', 'required', 'type', 'list', 'name' keys. v2 used flat key-value pairs.

fix

Use { variableName: { value: actualValue, required: true, type: 'String', list: false, name: 'argName' } } instead of { variableName: actualValue }.

affects: >=3.0.0

breakingIn v2, the default import was gql.query, gql.mutation. v3 changed to import * as gql from 'gql-query-builder' or named imports.

fix

Change import { query } from 'gql-query-builder' or import * as gql from 'gql-query-builder'. If using require, use const { query } = require('gql-query-builder').

affects: >=3.0.0

deprecatedThe 'adapter' parameter is marked as optional but its usage is not documented completely; future versions may remove it.

fix

Stick to default adapters unless you've implemented a custom one. Avoid relying on adapter feature for production.

affects: 3.x

gotchaWhen using array of operations (batch queries), each operation must have unique aliases to avoid name collisions.

fix

Use { operation: { name: 'op', alias: 'uniqueAlias' }, ... } for each operation in the array.

affects: >=3.0.0

gotchaThe 'type' field in variables is case-sensitive and must match GraphQL scalar types (e.g., 'String', 'Int', 'Float'). Using lowercase 'string' will not generate the type correctly.

fix

Always use proper GraphQL type names with correct casing (e.g., 'String' not 'string', 'Int' not 'int').

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: gql.query is not a function

Using incorrect import style importing whole module as default instead of named import.

fix

Use import { query } from 'gql-query-builder' or import * as gql from 'gql-query-builder' then gql.query(...).

Variable "$id" is not defined

Variables declared but not referenced in the operation due to missing variable definition in options.

fix

Ensure variables object includes both 'value' and 'required' for each variable you want to be passed; the operation string will automatically add the variable declaration.

Cannot find module 'gql-query-builder' or its corresponding type declarations

Package is not installed or TypeScript cannot resolve types because it lacks a types field in package.json.

fix

Install with npm install gql-query-builder and ensure tsconfig.json includes 'node_modules' in typeRoots or the package's types are picked up automatically.

Expected 0 arguments, but got 1

Passing options object to a function that expects no arguments (usually due to wrong import).

fix

Ensure you are using the default import correctly: import gql from 'gql-query-builder' and then call gql.query(options).

Upgrade

Version history

3.8.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

67 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/atulmy/gql-query-builder ↗

packagegql-query-builder ↗

homepagehttps://github.com/atulmy/gql-query-builder ↗