{"id":13258,"library":"graphql.macro","title":"GraphQL Build-Time AST Compilation Macro","description":"`graphql.macro` is a build-time tool that compiles GraphQL Abstract Syntax Trees (AST) using `babel-plugin-macros`. Its primary function is to eliminate the runtime parsing overhead associated with GraphQL query strings, transforming them into pre-parsed AST objects during the build process. The current stable version is 1.4.2. While not actively developed with frequent releases, it provides a stable solution for projects leveraging Babel macros to optimize GraphQL operations. Key differentiators include its integration with the `babel-plugin-macros` ecosystem, offering a declarative way to handle GraphQL documents without explicit Webpack loaders or complex Babel plugins, and replacing runtime libraries like `graphql-tag` for parsing. This approach streamlines the development workflow by allowing GraphQL documents to be imported directly or defined inline, with the macro handling the static transformation.","status":"maintenance","version":"1.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/evenchange4/graphql.macro","tags":["javascript","typescript"],"install":[{"cmd":"npm install graphql.macro","lang":"bash","label":"npm"},{"cmd":"yarn add graphql.macro","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql.macro","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"`graphql.macro` is implemented as a Babel macro and fundamentally requires `babel-plugin-macros` to be installed and configured in your Babel setup to function.","package":"babel-plugin-macros","optional":false}],"imports":[{"note":"Used to import GraphQL files (e.g., `.graphql`, `.gql`) directly, compiling them into an AST object at build time. The CommonJS `require` syntax will not be processed by the macro system.","wrong":"const { loader } = require('graphql.macro');","symbol":"loader","correct":"import { loader } from 'graphql.macro';"},{"note":"Provides a tagged template literal similar to `graphql-tag` but performs the AST compilation at build time via the macro. Using `graphql-tag` imports runtime parsing.","wrong":"import gql from 'graphql-tag';","symbol":"gql","correct":"import { gql } from 'graphql.macro';"}],"quickstart":{"code":"// .babelrc.js or babel.config.js\nmodule.exports = {\n  plugins: ['babel-plugin-macros'],\n};\n\n// src/myQuery.graphql\n// query UserProfile($id: ID!) {\n//   user(id: $id) {\n//     name\n//     email\n//   }\n// }\n\n// src/app.ts\nimport { loader, gql } from 'graphql.macro';\nimport type { DocumentNode } from 'graphql';\n\n// Compile a .graphql file at build time\nconst UserProfileQuery: DocumentNode = loader('./myQuery.graphql');\n\n// Compile an inline GraphQL string at build time\nconst AllUsersQuery: DocumentNode = gql`\n  query AllUsers {\n    users {\n      id\n      name\n    }\n  }\n`;\n\nconsole.log('User Profile Query AST:', JSON.stringify(UserProfileQuery, null, 2));\nconsole.log('All Users Query AST:', JSON.stringify(AllUsersQuery, null, 2));\n// UserProfileQuery and AllUsersQuery are now plain JavaScript objects representing the GraphQL AST.\n","lang":"typescript","description":"Demonstrates how to configure Babel for `graphql.macro` and use both the `loader` and `gql` functions to compile GraphQL documents into AST objects at build time."},"warnings":[{"fix":"Install `babel-plugin-macros` (`yarn add -D babel-plugin-macros` or `npm install --save-dev babel-plugin-macros`) and add it to your Babel configuration (e.g., `plugins: ['babel-plugin-macros']` in `.babelrc` or `babel.config.js`).","message":"This package requires `babel-plugin-macros` to be correctly installed and configured in your Babel environment. `graphql.macro` will not function without this prerequisite, as it is fundamentally a macro.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure your development build pipeline is efficient for rapid iteration. For projects with hot module reloading, confirm that changes to GraphQL files are properly detected and trigger a macro re-processing.","message":"`graphql.macro` performs build-time compilation, meaning the GraphQL AST is embedded directly into your compiled JavaScript bundle. While this eliminates runtime parsing overhead, any changes to GraphQL documents (e.g., `.graphql` files or `gql` template literals) require a full rebuild to take effect.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Standardize on either build-time macros (`graphql.macro`) or a runtime parsing library (`graphql-tag`) consistently across your project to maintain a clear parsing strategy and optimize bundle size.","message":"This package provides a build-time alternative to runtime GraphQL parsing libraries like `graphql-tag`. While `graphql-tag` is not deprecated, using both `graphql.macro` and `graphql-tag` for similar purposes can lead to inconsistencies, larger bundle sizes, or confusion regarding parsing behavior.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `yarn add -D babel-plugin-macros` or `npm install --save-dev babel-plugin-macros` and ensure your Babel configuration (e.g., `.babelrc` or `babel.config.js`) explicitly includes `babel-plugin-macros` in the plugins array.","cause":"`babel-plugin-macros` is not installed or not correctly configured in your Babel setup, preventing the macro from being resolved.","error":"Module build failed (from ../node_modules/babel-loader/lib/index.js): Error: Cannot find module 'babel-plugin-macros/dist/macro-context'"},{"fix":"Create a declaration file (e.g., `src/custom.d.ts`) in your project with `declare module '*.graphql' { const content: import('graphql').DocumentNode; export default content; }` to inform TypeScript about the module type for GraphQL files. Adjust for `.gql` if necessary.","cause":"TypeScript does not natively understand or provide type declarations for `.graphql` or `.gql` file imports, leading to a module resolution error.","error":"Cannot find module './myQuery.graphql' or its corresponding type declarations.ts(2307)"},{"fix":"Verify your Babel configuration to ensure that the files using `graphql.macro` are within Babel's transpilation scope and that `babel-plugin-macros` is listed and active in your plugin configuration.","cause":"The files containing `graphql.macro` imports are not being processed by Babel with `babel-plugin-macros` enabled. The macro transformation is not occurring, leaving the imports as unresolved or empty objects.","error":"TypeError: Object(...) is not a function (when calling gql or loader)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}