gql-ast

library3.11.0jsnpmunverified

A utility library for constructing, parsing, and manipulating GraphQL ASTs programmatically. Version 3.11.0 is current, with regular weekly releases. Unlike codegen-based tools, gql-ast provides a lightweight, type-safe way to build and inspect GraphQL documents and schemas in JavaScript/TypeScript without a runtime dependency on GraphQL.js. Ships full TypeScript definitions and is ESM-first since v3.

devops

npm install gql-ast

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GQL-AST

gql-ast

devopsjavascriptv3.11.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.

buildAST

✓ import { buildAST } from 'gql-ast'

✗ const { buildAST } = require('gql-ast')

ESM-only since v3; CommonJS require will fail.

parse

✓ import { parse } from 'gql-ast'

Named export for parsing GraphQL strings into AST nodes.

printAST

✓ import { printAST } from 'gql-ast'

✗ import printAST from 'gql-ast'

Default export is not available; always use named import.

Type

✓ import { Type } from 'gql-ast'

✗ import { GraphQLString } from 'graphql'

gql-ast provides its own type constants, not from graphql-js.

Parses a GraphQL schema string and builds an AST using gql-ast.

import { buildAST, parse } from 'gql-ast'; const schema = ` type Query { hello: String } `; const doc = parse(schema); const types = buildAST(doc); console.log(types);

Debug

Known issues

breakingv3 dropped CommonJS support entirely. Calling require('gql-ast') will throw 'ERR_REQUIRE_ESM'.

fix

Switch to ES module import syntax. If you must use CommonJS, stay on v2.x.

affects: >=3.0.0

breakingIn v3.0, the export 'gql' was renamed to 'buildAST'.

fix

Replace `import { gql } from 'gql-ast'` with `import { buildAST } from 'gql-ast'`.

affects: >=3.0.0

deprecatedThe function 'print' is deprecated since v3.10 and will be removed in v4. Use 'printAST' instead.

fix

Replace `print(doc)` with `printAST(doc)`.

affects: >=3.10.0

gotchaType constants like 'String', 'Int' are not GraphQL.js types; they are internal AST node representations. Do not mix with graphql-js's GraphQLScalarType.

fix

Use gql-ast types only for AST building; convert to graphql-js if needed.

affects: >=1.0.0

gotchaParsing schema definitions with extensions (e.g., 'extend type Query') may produce unexpected AST nodes in versions <3.8.

fix

Upgrade to v3.8+ for proper extension support.

affects: <3.8.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module

Using require() on v3.x which is ESM-only.

fix

Use `import` syntax or downgrade to v2.x.

TypeError: (0 , _gqlAst.buildAST) is not a function

Using 'gql' export which was renamed in v3.0.

fix

Import 'buildAST' instead of 'gql'.

Module '"gql-ast"' has no exported member 'print'.

The 'print' function was renamed to 'printAST' in v3.10.

fix

Use 'printAST' export.

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

Attempting to use gql-ast types (e.g., 'String') as if they were graphql-js scalars.

fix

Use 'Type.String' from gql-ast for AST construction, not graphql-js types.

Upgrade

Version history

3.11.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/constructive-io/constructive ↗

packagegql-ast ↗

homepagehttps://github.com/constructive-io/constructive ↗