{"id":15331,"library":"graphile-build","title":"Graphile Build","description":"Graphile Build is a robust framework for constructing extensible GraphQL APIs, primarily through the composition of small, purpose-built plugins. It enables developers to define broad changes to their GraphQL schema with minimal code, ensuring consistency across the API. The library, currently at version 5.0.0, integrates strongly with Gra*fast* for building high-performance, auto-generated, or generator-assisted GraphQL APIs. It forms the core of projects like PostGraphile, which leverages `graphile-build` and Gra*fast* to create robust, standards-compliant GraphQL APIs from PostgreSQL schemas. While `graphile-build` itself is database-agnostic, modules like `graphile-build-pg` provide PostgreSQL-specific plugins. Its release cadence aligns with the broader Graphile ecosystem, with frequent patch releases addressing bug fixes and performance enhancements, as seen in recent updates across related packages like `grafast` and `graphile-config`. Key differentiators include its plugin-first architecture, strong TypeScript support, and deep integration with Gra*fast* for advanced performance optimization.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/graphile/crystal","tags":["javascript","graphile","graphql","engine","apollo","graphqljs","plugin","build","extension","typescript"],"install":[{"cmd":"npm install graphile-build","lang":"bash","label":"npm"},{"cmd":"yarn add graphile-build","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphile-build","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for high-performance GraphQL execution layer, tightly integrated with Graphile Build.","package":"grafast","optional":false},{"reason":"Provides the configuration system for Graphile ecosystem libraries, including plugin management.","package":"graphile-config","optional":false},{"reason":"The foundational GraphQL.js library for schema definition and execution.","package":"graphql","optional":false}],"imports":[{"note":"Graphile Build v5 is an ESM-first package and requires Node.js >=22. Use ES module import syntax.","wrong":"const { makeSchema } = require('graphile-build');","symbol":"makeSchema","correct":"import { makeSchema } from 'graphile-build';"},{"note":"Import the `Plugin` type for defining custom plugins within the Graphile Build ecosystem.","symbol":"Plugin","correct":"import type { Plugin } from 'graphile-build';"},{"note":"Import the `Build` type to get access to the GraphQL schema building context within plugin hooks.","symbol":"Build","correct":"import type { Build } from 'graphile-build';"}],"quickstart":{"code":"import { makeSchema, Plugin } from 'graphile-build';\nimport { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';\n\n// Define a simple plugin that adds a 'hello' field to the Query type\nconst HelloPlugin: Plugin = (builder) => {\n  builder.hook(\"GraphQLObjectType:fields\", (fields, build, context) => {\n    const { Self, scope } = context;\n    // Ensure we are modifying the root Query type\n    if (scope.isRootQuery) {\n      return {\n        ...fields,\n        hello: {\n          type: GraphQLString,\n          resolve: () => \"Hello from Graphile Build!\",\n          description: \"A simple greeting field.\"\n        },\n      };\n    }\n    return fields;\n  });\n};\n\nasync function main() {\n  try {\n    const schema: GraphQLSchema = await makeSchema({\n      plugins: [HelloPlugin],\n      // Additional options can be passed here\n    });\n\n    console.log(\"GraphQL schema built successfully!\");\n\n    // Verify the 'hello' field exists on the Query type\n    const queryType = schema.getQueryType();\n    if (queryType) {\n      const helloField = queryType.getFields().hello;\n      console.log(`Query type has 'hello' field: ${!!helloField}`);\n      if (helloField) {\n        console.log(`Hello field description: \"${helloField.description}\"`);\n      }\n    }\n\n    // Example: You could now use this schema with a GraphQL server\n    // import { graphql } from 'graphql';\n    // const result = await graphql({ schema, source: '{ hello }' });\n    // console.log(result.data?.hello);\n\n  } catch (error) {\n    console.error(\"Error building schema:\", error);\n  }\n}\n\nmain();","lang":"typescript","description":"Demonstrates how to initialize Graphile Build, define a simple plugin, and build a basic GraphQL schema with a custom field."},"warnings":[{"fix":"Upgrade your Node.js environment to version 22 or newer.","message":"Graphile Build v5 requires Node.js version 22 or higher. Running on older Node.js versions will result in execution errors.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Graphile Build v5 is an ESM-first package. CommonJS (require()) syntax is not supported and will lead to `ERR_REQUIRE_ESM` errors.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Consult the official Graphile v5 migration guides and documentation for detailed instructions on updating custom plugins.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","cause":"Attempting to use `require()` to import `graphile-build` which is an ES Module.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/graphile-build/dist/index.js from .../my-project/index.js not supported."},{"fix":"Install `graphql` using `npm install graphql` or `yarn add graphql`. Ensure its version is compatible with `graphile-build` v5 (currently `^16.9.0`).","cause":"The peer dependency `graphql` is not installed or is an incompatible version.","error":"node:internal/modules/cjs/loader:1293\n  throw err;\n  ^\nError: Cannot find module 'graphql'"},{"fix":"Update your Node.js environment to version 22 or higher. Consider using `nvm` (Node Version Manager) to manage multiple Node.js versions.","cause":"Running `graphile-build` on an unsupported Node.js version.","error":"The engine \"node\" is incompatible with this module. Expected version \">=22\". Got \"XX.YY.ZZ\""}],"ecosystem":"npm"}