{"id":16044,"library":"graphql-import-macro","title":"GraphQL Import Macro","description":"graphql-import-macro is a utility library designed to parse and expand GraphQL import statements within GraphQL document definitions. It aims to provide a reference implementation for a relatively standardized GraphQL import syntax, emphasizing minimal dependencies. The library enables the DRY principle in GraphQL documents by allowing modularization and reuse of schema fragments. The current stable version is 1.0.0, released in April 2020. There have been no subsequent updates, suggesting it is no longer actively maintained. Its primary differentiator is its focus on being a lightweight, standalone parser for tools that need to support GraphQL imports, without aiming to become part of the official GraphQL specification.","status":"abandoned","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/squirly/graphql-import-macro","tags":["javascript","graphql"],"install":[{"cmd":"npm install graphql-import-macro","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-import-macro","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-import-macro","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for parsing and working with GraphQL ASTs. This library builds upon its DocumentNode structure.","package":"graphql","optional":false}],"imports":[{"note":"Primarily designed for ES modules. CommonJS `require` might work but isn't the idiomatic usage shown in documentation.","wrong":"const { processDocumentImports } = require('graphql-import-macro');","symbol":"processDocumentImports","correct":"import { processDocumentImports } from 'graphql-import-macro';"},{"note":"The `parse` function is a named export from the `graphql` package, not a default export.","wrong":"import parse from 'graphql';","symbol":"parse","correct":"import { parse } from 'graphql';"},{"note":"The `Source` class is a named export from the `graphql` package, essential for attaching path information to ASTs processed by this macro.","wrong":"const { Source } = require('graphql');","symbol":"Source","correct":"import { Source } from 'graphql';"}],"quickstart":{"code":"import { parse, Source } from \"graphql\";\nimport { processDocumentImports } from \"graphql-import-macro\";\n\nasync function loadAndProcessGraphQL(content, path) {\n  // Ensure the Source is instantiated with both content and path\n  const ast = parse(new Source(content, path));\n\n  // Process and expand GraphQL import directives\n  const resolvedAst = await processDocumentImports(ast);\n\n  return resolvedAst;\n}\n\n// Example usage (replace with actual file content and path)\nconst sampleGraphQLContent = `\n  #import './another.graphql'\n  type Query {\n    hello: String\n  }\n`;\n\nconst sampleGraphQLPath = 'schema.graphql';\n\nloadAndProcessGraphQL(sampleGraphQLContent, sampleGraphQLPath)\n  .then(ast => console.log(JSON.stringify(ast, null, 2)))\n  .catch(error => console.error('Error processing GraphQL:', error));\n","lang":"javascript","description":"Demonstrates how to parse a GraphQL document, process its imports, and log the resolved AST."},"warnings":[{"fix":"Thoroughly test with your specific `graphql` package version. Consider alternative solutions for GraphQL imports if compatibility issues arise with newer GraphQL versions.","message":"The library has not been updated since April 2020. It may not be compatible with newer versions of the `graphql` package or recent changes in the GraphQL specification, potentially leading to parsing errors or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all tools in your GraphQL workflow (e.g., build tools, linters, servers) are aware of and correctly process the expanded GraphQL documents, or implement custom pre-processing steps.","message":"The `#import` syntax utilized by this library is a convention and not part of the official GraphQL specification. Tools or clients that do not explicitly support this convention will not recognize these directives.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always instantiate `graphql.Source` with both the content string and the file path (e.g., `new Source(content, path)`).","message":"The library expects `DocumentNode` instances to be created from `Source` objects that include path information. Omitting the path will result in errors when `processDocumentImports` attempts to resolve relative imports.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `graphql.Source` is created with both the GraphQL content and its originating file path: `new Source(content, 'path/to/file.graphql')`.","cause":"The `parse` function was called with a `Source` object missing the `name` (path) argument.","error":"Error: DocumentNode must be created from a Source instantiated with at least two parameters."},{"fix":"Verify that `graphql-import-macro` is installed (`npm install graphql-import-macro`) and that you are using the correct named import: `import { processDocumentImports } from 'graphql-import-macro';`.","cause":"Incorrect import statement or `graphql-import-macro` not installed/found.","error":"TypeError: Cannot read properties of undefined (reading 'processDocumentImports')"},{"fix":"Install the `graphql` package: `npm install graphql` (or `yarn add graphql`).","cause":"The peer dependency `graphql` is not installed in the project.","error":"Cannot find module 'graphql'"}],"ecosystem":"npm"}