Graphile Build

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/graphile-build/dist/index.js from .../my-project/index.js not supported.

  cause Attempting to use `require()` to import `graphile-build` which is an ES Module.
  fix Change your import statement to `import { makeSchema } from 'graphile-build';` and ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json` or using `.mjs` file extensions).

• node:internal/modules/cjs/loader:1293
    throw err;
    ^
  Error: Cannot find module 'graphql'

  cause The peer dependency `graphql` is not installed or is an incompatible version.
  fix Install `graphql` using `npm install graphql` or `yarn add graphql`. Ensure its version is compatible with `graphile-build` v5 (currently `^16.9.0`).

• The engine "node" is incompatible with this module. Expected version ">=22". Got "XX.YY.ZZ"

  cause Running `graphile-build` on an unsupported Node.js version.
  fix Update your Node.js environment to version 22 or higher. Consider using `nvm` (Node Version Manager) to manage multiple Node.js versions.

Warnings

• breaking Graphile Build v5 requires Node.js version 22 or higher. Running on older Node.js versions will result in execution errors.
  Fix: Upgrade your Node.js environment to version 22 or newer.
• breaking Graphile Build v5 is an ESM-first package. CommonJS (require()) syntax is not supported and will lead to `ERR_REQUIRE_ESM` errors.
  Fix: Ensure your project uses ES Modules (ESM) and update all import statements to `import ... from 'graphile-build'` syntax. Configure your `package.json` with `"type": "module"` if necessary, or use a `.mjs` extension for files.
• breaking The plugin API surface has undergone significant changes from v4 to v5 to align with Gra*fast* and `graphile-config`. Existing v4 plugins will require refactoring.
  Fix: Consult the official Graphile v5 migration guides and documentation for detailed instructions on updating custom plugins.
• gotcha Graphile Build has peer dependencies on `grafast`, `graphile-config`, and `graphql`. Mismatched or missing peer dependency versions can lead to runtime errors or unexpected behavior.
  Fix: Ensure that `grafast`, `graphile-config`, and `graphql` are installed in your project at versions compatible with `graphile-build` v5 (refer to `peerDependencies` in `package.json`).

Install

• npm install graphile-build npm
• yarn add graphile-build yarn
• pnpm add graphile-build pnpm

Imports

• makeSchema
  wrong:

  const { makeSchema } = require('graphile-build');

  correct:

  import { makeSchema } from 'graphile-build';

  Graphile Build v5 is an ESM-first package and requires Node.js >=22. Use ES module import syntax.
• Plugin

  import type { Plugin } from 'graphile-build';

  Import the `Plugin` type for defining custom plugins within the Graphile Build ecosystem.
• Build

  import type { Build } from 'graphile-build';

  Import the `Build` type to get access to the GraphQL schema building context within plugin hooks.

Quickstart

Demonstrates how to initialize Graphile Build, define a simple plugin, and build a basic GraphQL schema with a custom field.

import { makeSchema, Plugin } from 'graphile-build';
import { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';

// Define a simple plugin that adds a 'hello' field to the Query type
const HelloPlugin: Plugin = (builder) => {
  builder.hook("GraphQLObjectType:fields", (fields, build, context) => {
    const { Self, scope } = context;
    // Ensure we are modifying the root Query type
    if (scope.isRootQuery) {
      return {
        ...fields,
        hello: {
          type: GraphQLString,
          resolve: () => "Hello from Graphile Build!",
          description: "A simple greeting field."
        },
      };
    }
    return fields;
  });
};

async function main() {
  try {
    const schema: GraphQLSchema = await makeSchema({
      plugins: [HelloPlugin],
      // Additional options can be passed here
    });

    console.log("GraphQL schema built successfully!");

    // Verify the 'hello' field exists on the Query type
    const queryType = schema.getQueryType();
    if (queryType) {
      const helloField = queryType.getFields().hello;
      console.log(`Query type has 'hello' field: ${!!helloField}`);
      if (helloField) {
        console.log(`Hello field description: "${helloField.description}"`);
      }
    }

    // Example: You could now use this schema with a GraphQL server
    // import { graphql } from 'graphql';
    // const result = await graphql({ schema, source: '{ hello }' });
    // console.log(result.data?.hello);

  } catch (error) {
    console.error("Error building schema:", error);
  }
}

main();