GraphQL Import Macro

1.0.0 · abandoned · verified Tue Apr 21

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.

Common errors

```
Error: DocumentNode must be created from a Source instantiated with at least two parameters.
```
cause The `parse` function was called with a `Source` object missing the `name` (path) argument.

fix Ensure `graphql.Source` is created with both the GraphQL content and its originating file path: `new Source(content, 'path/to/file.graphql')`.
```
TypeError: Cannot read properties of undefined (reading 'processDocumentImports')
```
cause Incorrect import statement or `graphql-import-macro` not installed/found.

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';`.
```
Cannot find module 'graphql'
```
cause The peer dependency `graphql` is not installed in the project.

fix Install the `graphql` package: `npm install graphql` (or `yarn add graphql`).

Warnings

gotcha 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.
Fix: Thoroughly test with your specific `graphql` package version. Consider alternative solutions for GraphQL imports if compatibility issues arise with newer GraphQL versions.
gotcha 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.
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.
gotcha 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.
Fix: Always instantiate `graphql.Source` with both the content string and the file path (e.g., `new Source(content, path)`).

Install

npm install graphql-import-macro npm
yarn add graphql-import-macro yarn
pnpm add graphql-import-macro pnpm

Imports

processDocumentImports
wrong:
```
const { processDocumentImports } = require('graphql-import-macro');
```
correct:
```
import { processDocumentImports } from 'graphql-import-macro';
```
Primarily designed for ES modules. CommonJS `require` might work but isn't the idiomatic usage shown in documentation.
parse
wrong:
```
import parse from 'graphql';
```
correct:
```
import { parse } from 'graphql';
```
The `parse` function is a named export from the `graphql` package, not a default export.
Source
wrong:
```
const { Source } = require('graphql');
```
correct:
```
import { Source } from 'graphql';
```
The `Source` class is a named export from the `graphql` package, essential for attaching path information to ASTs processed by this macro.

Quickstart

Demonstrates how to parse a GraphQL document, process its imports, and log the resolved AST.

import { parse, Source } from "graphql";
import { processDocumentImports } from "graphql-import-macro";

async function loadAndProcessGraphQL(content, path) {
  // Ensure the Source is instantiated with both content and path
  const ast = parse(new Source(content, path));

  // Process and expand GraphQL import directives
  const resolvedAst = await processDocumentImports(ast);

  return resolvedAst;
}

// Example usage (replace with actual file content and path)
const sampleGraphQLContent = `
  #import './another.graphql'
  type Query {
    hello: String
  }
`;

const sampleGraphQLPath = 'schema.graphql';

loadAndProcessGraphQL(sampleGraphQLContent, sampleGraphQLPath)
  .then(ast => console.log(JSON.stringify(ast, null, 2)))
  .catch(error => console.error('Error processing GraphQL:', error));

view raw JSON →