Registry / web-framework / graphile-build

graphile-build

JSON →
library5.0.0jsnpmunverified

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.

npm install graphile-build
INSTALL
IMPORT
SIG · GRAPHILE-BUILD
G
graphile-build
web-frameworkjavascriptv5.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

makeSchema
import { makeSchema } from 'graphile-build';
const { makeSchema } = require('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.

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();
Debug
Known issues
breakingGraphile 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.
affects: >=5.0.0
breakingGraphile 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.
affects: >=5.0.0
breakingThe 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.
affects: >=5.0.0
gotchaGraphile 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`).
affects: >=5.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/graphile-build/dist/index.js from .../my-project/index.js not supported.
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'
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"
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.
Upgrade
Version history
5.0.0latest on npm
Audit
Dependencies
grafastrequiredCore dependency for high-performance GraphQL execution layer, tightly integrated with Graphile Build.
graphile-configrequiredProvides the configuration system for Graphile ecosystem libraries, including plugin management.
graphqlrequiredThe foundational GraphQL.js library for schema definition and execution.
Agent activity
8 hits · last 30 days
node
8
Resources
graphile-build — npm install graphile-build · libregistry