graphql-tag

graphql-tag provides the gql template literal tag that turns GraphQL query strings into the standard GraphQL AST used by Apollo Client and other GraphQL clients. It also ships a webpack loader for precompiling .graphql/.gql files at build time.

The library focuses on doing one job well: parsing and caching. Repeated calls to gql with the same normalized query string reuse a cached AST instead of re-parsing, which lets application code use === comparisons on parsed documents and avoids redundant parsing work on hot paths like re-rendering React components.

What You Get

• The gql template literal tag for writing GraphQL queries and fragments inline in JavaScript/TypeScript
• Automatic caching of parsed ASTs keyed by normalized query source, avoiding repeat parsing
• Fragment composability via template literal interpolation, with duplicate-fragment-name warnings
• A graphql-tag/loader webpack loader for precompiling .graphql/.gql files into ASTs at build time
• Support for experimental parameterized fragment variables

Common Use Cases

• Writing GraphQL queries and mutations inline for Apollo Client or any other GraphQL client
• Composing reusable GraphQL fragments across multiple queries in a single application
• Precompiling .graphql files at build time via the webpack loader to cut client bundle parsing cost
• Statically analyzing GraphQL query strings with tools like eslint-plugin-graphql

Under The Hood

Architecture graphql-tag is a single-module library (src/index.ts) built around one exported function, gql, plus a handful of cache-management helpers (resetCaches, disableFragmentWarnings, enableExperimentalFragmentVariables). Internally it maintains two module-level caches: a Map<string, DocumentNode> keyed by whitespace-normalized query source (docCache), and a Map<fragmentName, Set<normalizedSource>> (fragmentSourceMap) used to detect and warn about fragments that share a name but differ in source. gql concatenates template literal segments and any interpolated sub-documents’ original source text, normalizes whitespace, and looks up or parses the result via the graphql package’s parse(), then strips loc/token metadata before caching and returning the AST. A companion loader.js wraps this same logic as a webpack loader so .graphql/.gql files can be precompiled to ASTs at build time instead of parsed at runtime.

Tech Stack Written in TypeScript, compiled via a custom run_tsc.sh plus Rollup (rollup.config.js) into CommonJS/ESM/UMD outputs, with a single runtime dependency (tslib) and graphql as a peer dependency (supporting a wide peer range from 0.9 through 17.x). Tests run through Mocha against lib/tests.cjs.js after a build step, and the project is versioned/released via Changesets.

Code Quality The package is tiny and has one dense test file (src/tests.ts, ~16KB) covering caching behavior, fragment warnings, and experimental fragment variables, run across multiple TypeScript/GraphQL peer version combinations (test:ts3, test:ts4) via test-all-versions before each publish. The core module itself has no runtime error handling beyond a single thrown Error('Not a valid GraphQL document.') for malformed input — appropriate given its narrow, single-purpose scope. Naming is consistent and the code is small enough to read end-to-end in minutes.

API Design The public API is minimal and idiomatic: a single default-exported tag function gql that doubles as a namespace object exposing its own helper methods (gql.gql, gql.resetCaches, etc.), requiring zero configuration to get started beyond import gql from 'graphql-tag'. This near-zero-boilerplate design, combined with broad ecosystem convention (virtually every GraphQL client library recognizes the gql tag pattern), makes it very approachable, though the module-level mutable caches and namespace-merging trick are somewhat unusual patterns for newcomers reading the source.