graphql-tag.macro

2.0.1 verified Sat Apr 25 auth: no javascript

graphql-tag.macro is a Babel macro that inlines GraphQL query parsing at build time, replacing the runtime call to graphql-tag's gql tag function with the pre-parsed AST. Version 2.0.1 is current, with TypeScript definitions added in 2.1.0. It requires babel-plugin-macros and works with any Babel-based build system. Unlike runtime graphql-tag, this macro eliminates parsing overhead in production bundles. It supports fragment interpolation and is primarily used in GraphQL client projects (Apollo, URQL). Release cadence is low; last major version bumped deps for compatibility.

Common errors

error Cannot find module 'graphql-tag.macro' ↓

cause Package not installed or missing from dependencies

fix

npm install --save-dev graphql-tag.macro

error gql is not a function ↓

cause Incorrect import – using named import instead of default, or missing .default in require

fix

Use import gql from 'graphql-tag.macro' or require('graphql-tag.macro').default

error Error: BabelMacro: Macro 'graphql-tag.macro' is not activated. Did you forget to add babel-plugin-macros to your plugins? ↓

cause babel-plugin-macros not configured in Babel

fix

Add 'macros' to Babel plugins: { "plugins": ["macros"] }

Warnings

gotcha Import path must be 'graphql-tag.macro' not 'graphql-tag' – using the runtime version will not inline and adds bundle size. ↓

fix Use import gql from 'graphql-tag.macro'

gotcha Require() in Node requires .default – const gql = require('graphql-tag.macro').default ↓

fix Add .default to the require() result

breaking v2.0.0 dropped support for older versions of babel-plugin-macros; requires at least version 2.0.0 of the plugin. ↓

fix Update babel-plugin-macros to >=2.0.0

Install

npm install graphql-tag.macro

yarn add graphql-tag.macro

pnpm add graphql-tag.macro

Imports

gql
wrong
```
import { gql } from 'graphql-tag'
```
correct
```
import gql from 'graphql-tag.macro'
```
Default import from the macro package. Named import from graphql-tag is the standard runtime version, not the macro.
gql
wrong
```
const gql = require('graphql-tag.macro')
```
correct
```
const gql = require('graphql-tag.macro').default
```
In CommonJS, the macro exports as default, so you need .default. The non-default export may not work as expected.

Quickstart

Shows installation, Babel macro setup, and usage of gql tag from the macro to inline parsed AST.

// Install: npm install --save-dev graphql-tag.macro babel-plugin-macros
// Then configure babel (in .babelrc or babel.config.js):
// {
//   "plugins": ["macros"]
// }

// Now in your code:
import gql from 'graphql-tag.macro';

const HELLO_QUERY = gql`
  query Hello {
    hello {
      world
    }
  }
`;

export default HELLO_QUERY;
// At build time, HELLO_QUERY becomes a pre-parsed AST object.
// No graphql-tag runtime needed in bundle.