Registry / http-networking / graphql-tag

graphql-tag

library2.12.6jsnpmunverified

graphql-tag is a JavaScript utility library that provides a template literal tag, `gql`, for parsing GraphQL query strings into the standard GraphQL Abstract Syntax Tree (AST). It is currently stable at version 2.12.6 and receives regular maintenance updates, including recent upgrades to support GraphQL 16. The library's primary function is to simplify the creation of GraphQL documents in application code, making them easily consumable by GraphQL clients like Apollo Client. A key differentiator is its built-in caching mechanism, which prevents redundant parsing of identical query strings and enables strict equality checks (`===`) between parsed query objects. It also includes a Webpack loader to allow direct importing of `.graphql` or `.gql` files, converting them into ASTs at build time. While it's particularly useful for static analysis tools like `eslint-plugin-graphql`, developers must explicitly embed fragment definitions within template literals even when spreading them to facilitate this analysis. It relies on the core `graphql` library as a peer dependency for its parsing capabilities.

http-networking

npm install graphql-tag

github ↗package ↗

INSTALL

IMPORT

SIG · GRAPHQL-TAG

graphql-tag

http-networkingjavascriptv2.12.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

gql

✓ import gql from 'graphql-tag';

✗ import { gql } from 'graphql-tag'; const gql = require('graphql-tag').gql;

`gql` is the default export of the `graphql-tag` package. It should be imported as a default, not a named export. For CommonJS, require the package directly.

resetCaches

✓ import { resetCaches } from 'graphql-tag';

✗ import resetCaches from 'graphql-tag';

Used to clear the internal cache of parsed GraphQL documents. This is a named export.

stripIgnoredCharacters

✓ import { stripIgnoredCharacters } from 'graphql-tag';

✗ import stripIgnoredCharacters from 'graphql-tag';

A utility function that removes comments and insignificant whitespace from a GraphQL string. This is a named export.

This quickstart demonstrates how to define GraphQL queries and fragments using the `gql` template literal tag, including how to embed fragments for reuse and static analysis, producing a standard GraphQL AST.

import gql from 'graphql-tag'; // Define a reusable fragment const UserFragment = gql` fragment User_details on User { id firstName lastName } `; // Embed the fragment in a query and export the final document const GetUserQuery = gql` query GetUser($id: ID!) { user(id: $id) { ...User_details } } ${UserFragment} // Crucial for static analysis and fragment inclusion `; // Example of using the parsed query (e.g., with Apollo Client) // console.log(GetUserQuery); // You can also define mutations or subscriptions similarly const CreateUserMutation = gql` mutation CreateUser($input: CreateUserInput!) { createUser(input: $input) { ...User_details } } ${UserFragment} `; console.log('Parsed Query Document:', GetUserQuery); console.log('Parsed Mutation Document:', CreateUserMutation);

Debug

Known issues

breakingVersion 2.12.6 updated `graphql-tag` to support `graphql` package version 16. While `graphql-tag` itself mostly adapts, this might introduce compatibility issues if your project depends on older `graphql` versions or specific features that changed between `graphql` 15 and 16.

fix

Ensure your project's `graphql` peer dependency is compatible with `graphql-tag` v2.12.6 and newer (i.e., `^15.0.0 || ^16.0.0`). Review your `graphql` schema and resolvers for any breaking changes introduced in `graphql` v16.

affects: >=2.12.6

gotchaThe `graphql` package is a peer dependency and must be explicitly installed alongside `graphql-tag`. Forgetting this will lead to runtime errors when `graphql-tag` attempts to parse queries.

fix

Install the `graphql` package: `npm install graphql` or `yarn add graphql`. Ensure its version satisfies the `graphql-tag` peer dependency range.

affects: >=0.9.0

gotchaWhen using fragments, you must explicitly embed the fragment variable into the template literal (e.g., `${User_details}`) AND spread the fragment within the GraphQL selection set (e.g., `...User_details`). Omitting the template literal embedding will result in the fragment not being included in the final AST, even if it's spread.

fix

Always include both the GraphQL spread (`...FragmentName`) in the selection set and the JavaScript template literal placeholder (`${FragmentVariable}`) in the `gql` tag when defining documents that use fragments.

affects: all

deprecatedThe `disableFragmentWarnings` named export was previously available but is now deprecated and removed. It was used to suppress warnings about unused fragments.

fix

Remove any usage of `disableFragmentWarnings`. If you encounter fragment warnings, ensure all defined fragments are either used or removed to maintain clean GraphQL documents.

affects: >=2.11.0

Errors

Common errors & fixes

Error: Must provide document

Attempting to call `gql` with an empty string or a non-string value, or with a string that is not a valid GraphQL document structure.

fix

Ensure the template literal passed to `gql` contains a syntactically valid GraphQL query, mutation, subscription, or fragment definition.

TypeError: Cannot read properties of undefined (reading 'kind') OR TypeError: query.definitions is not iterable

This often happens when `gql` is not correctly imported (e.g., `import { gql } from 'graphql-tag';` instead of `import gql from 'graphql-tag';`), leading to `gql` being undefined or not the expected function.

fix

Verify that `gql` is imported as the default export: `import gql from 'graphql-tag';` for ESM, or `const gql = require('graphql-tag');` for CommonJS.

Syntax Error: Expected Name, found { OR Syntax Error: Expected Name, found '...' (for fragments)

The GraphQL string within the `gql` template literal contains a syntax error according to the GraphQL specification.

fix

Carefully review your GraphQL query, mutation, or fragment string for typos, missing commas, incorrect field names, or improper syntax. Tools like `eslint-plugin-graphql` can help catch these errors statically.

Upgrade

Version history

2.12.6latest on npm

Audit

Dependencies

graphqlrequiredRequired peer dependency for GraphQL parsing functionality. `graphql-tag` uses the reference `graphql` library under the hood.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/apollographql/graphql-tag ↗

packagehttps://www.npmjs.com/package/graphql-tag ↗