{"id":10971,"library":"graphql-tag","title":"GraphQL Tag","description":"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.","status":"active","version":"2.12.6","language":"javascript","source_language":"en","source_url":"https://github.com/apollographql/graphql-tag","tags":["javascript","typescript"],"install":[{"cmd":"npm install graphql-tag","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-tag","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-tag","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for GraphQL parsing functionality. `graphql-tag` uses the reference `graphql` library under the hood.","package":"graphql","optional":false}],"imports":[{"note":"`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.","wrong":"import { gql } from 'graphql-tag';\nconst gql = require('graphql-tag').gql;","symbol":"gql","correct":"import gql from 'graphql-tag';"},{"note":"Used to clear the internal cache of parsed GraphQL documents. This is a named export.","wrong":"import resetCaches from 'graphql-tag';","symbol":"resetCaches","correct":"import { resetCaches } from 'graphql-tag';"},{"note":"A utility function that removes comments and insignificant whitespace from a GraphQL string. This is a named export.","wrong":"import stripIgnoredCharacters from 'graphql-tag';","symbol":"stripIgnoredCharacters","correct":"import { stripIgnoredCharacters } from 'graphql-tag';"}],"quickstart":{"code":"import gql from 'graphql-tag';\n\n// Define a reusable fragment\nconst UserFragment = gql`\n  fragment User_details on User {\n    id\n    firstName\n    lastName\n  }\n`;\n\n// Embed the fragment in a query and export the final document\nconst GetUserQuery = gql`\n  query GetUser($id: ID!) {\n    user(id: $id) {\n      ...User_details\n    }\n  }\n  ${UserFragment} // Crucial for static analysis and fragment inclusion\n`;\n\n// Example of using the parsed query (e.g., with Apollo Client)\n// console.log(GetUserQuery);\n\n// You can also define mutations or subscriptions similarly\nconst CreateUserMutation = gql`\n  mutation CreateUser($input: CreateUserInput!) {\n    createUser(input: $input) {\n      ...User_details\n    }\n  }\n  ${UserFragment}\n`;\n\nconsole.log('Parsed Query Document:', GetUserQuery);\nconsole.log('Parsed Mutation Document:', CreateUserMutation);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=2.12.6"},{"fix":"Install the `graphql` package: `npm install graphql` or `yarn add graphql`. Ensure its version satisfies the `graphql-tag` peer dependency range.","message":"The `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.","severity":"gotcha","affected_versions":">=0.9.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"The `disableFragmentWarnings` named export was previously available but is now deprecated and removed. It was used to suppress warnings about unused fragments.","severity":"deprecated","affected_versions":">=2.11.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the template literal passed to `gql` contains a syntactically valid GraphQL query, mutation, subscription, or fragment definition.","cause":"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.","error":"Error: Must provide document"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'kind') OR TypeError: query.definitions is not iterable"},{"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.","cause":"The GraphQL string within the `gql` template literal contains a syntax error according to the GraphQL specification.","error":"Syntax Error: Expected Name, found { OR Syntax Error: Expected Name, found '...' (for fragments)"}],"ecosystem":"npm"}