{"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,"search_vec":"'2.0.1':34 '2.1.0':42 'ad':40 'apollo':83 'ast':32 'babel':5,46,54 'babel-bas':53 'babel-plugin-macro':45 'base':55 'build':13,56 'bump':92 'bundl':70 'cadenc':86 'call':18 'client':81 'compat':95 'current':36 'definit':39 'dep':93 'elimin':65 'fragment':73 'function':26 'gql':24 'graphql':9,21,61,80 'graphql-tag':20,60 'graphql-tag.macro':1,2 'inlin':8 'interpol':74 'javascript':96 'last':89 'low':88 'macro':6,48,64 'major':90 'overhead':67 'pars':11,31,66 'plugin':47 'pre':30 'pre-pars':29 'primarili':77 'product':69 'project':82 'queri':10 'releas':85 'replac':15 'requir':44 'runtim':17,59 'support':72 'system':57 'tag':22,25,62 'time':14 'typescript':38,97 'unlik':58 'urql':84 'use':78 'version':33,91 'work':50","created_at":"2026-04-25T11:21:10.822968+00:00","updated_at":"2026-04-25T11:21:10.822968+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/graphql-tag.macro","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-24","install_tag":null}}