{"id":20072,"library":"graphql-tag.macro","title":"graphql-tag.macro","description":"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.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/leoasis/graphql-tag.macro","tags":["javascript","typescript"],"install":[{"cmd":"npm install graphql-tag.macro","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-tag.macro","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-tag.macro","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for graphql-tag itself used by some configurations","package":"graphql-tag","optional":true},{"reason":"Required peer – the macro system needed to run this macro","package":"babel-plugin-macros","optional":false}],"imports":[{"note":"Default import from the macro package. Named import from graphql-tag is the standard runtime version, not the macro.","wrong":"import { gql } from 'graphql-tag'","symbol":"gql","correct":"import gql from 'graphql-tag.macro'"},{"note":"In CommonJS, the macro exports as default, so you need .default. The non-default export may not work as expected.","wrong":"const gql = require('graphql-tag.macro')","symbol":"gql","correct":"const gql = require('graphql-tag.macro').default"}],"quickstart":{"code":"// Install: npm install --save-dev graphql-tag.macro babel-plugin-macros\n// Then configure babel (in .babelrc or babel.config.js):\n// {\n//   \"plugins\": [\"macros\"]\n// }\n\n// Now in your code:\nimport gql from 'graphql-tag.macro';\n\nconst HELLO_QUERY = gql`\n  query Hello {\n    hello {\n      world\n    }\n  }\n`;\n\nexport default HELLO_QUERY;\n// At build time, HELLO_QUERY becomes a pre-parsed AST object.\n// No graphql-tag runtime needed in bundle.\n","lang":"typescript","description":"Shows installation, Babel macro setup, and usage of gql tag from the macro to inline parsed AST."},"warnings":[{"fix":"Use import gql from 'graphql-tag.macro'","message":"Import path must be 'graphql-tag.macro' not 'graphql-tag' – using the runtime version will not inline and adds bundle size.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add .default to the require() result","message":"Require() in Node requires .default – const gql = require('graphql-tag.macro').default","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Update babel-plugin-macros to >=2.0.0","message":"v2.0.0 dropped support for older versions of babel-plugin-macros; requires at least version 2.0.0 of the plugin.","severity":"breaking","affected_versions":"<2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"npm install --save-dev graphql-tag.macro","cause":"Package not installed or missing from dependencies","error":"Cannot find module 'graphql-tag.macro'"},{"fix":"Use import gql from 'graphql-tag.macro' or require('graphql-tag.macro').default","cause":"Incorrect import – using named import instead of default, or missing .default in require","error":"gql is not a function"},{"fix":"Add 'macros' to Babel plugins: { \"plugins\": [\"macros\"] }","cause":"babel-plugin-macros not configured in Babel","error":"Error: BabelMacro: Macro 'graphql-tag.macro' is not activated. Did you forget to add babel-plugin-macros to your plugins?"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}