`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.
npm install graphql.macroVerified import paths — ran on the pinned version, not inferred.
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.
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`).
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.
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.
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.
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.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.