# graphile-utils
> Utilities to help with building graphile-build plugins
Latest version **5.0.3** (published 2026-07-22) · MIT license · 0 weekly downloads
## Install
```sh
npm install graphile-utils
pnpm add graphile-utils
yarn add graphile-utils
bun add graphile-utils
```
## Health
**Score 75/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; popular repo.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 5.0.3 |
| Published | 2026-07-22 |
| First published | 2018-06-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 3 |
| Unpacked size | 237.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 12929 |
| Author | Benjie Gillam |
| Maintainers | benjie |
| Keywords | graphile, graphql, engine, plugin, build, extension, utils, utilities, graphite |
## Links
- npm: https://www.npmjs.com/package/graphile-utils
- Repository: https://github.com/graphile/crystal
- Homepage: https://github.com/graphile/crystal/tree/main/graphile-build/graphile-utils
- Issues: https://github.com/graphile/crystal/issues
- npm.io page: https://npm.io/package/graphile-utils
## Dependencies (3)
- [debug](https://npm.io/package/debug.md) ^4.4.3
- [json5](https://npm.io/package/json5.md) ^2.2.3
- [tslib](https://npm.io/package/tslib.md) ^2.8.1
## Alternatives
- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads
## Recent versions
- 5.0.3 (latest) — 2026-07-22
- 5.1.0-aardvark.next-20260928202932 (snapshot-next) — 2026-09-28
- 5.0.0-rc.8 (rc) — 2026-03-10
- 5.0.0-beta.45 (beta) — 2025-09-24
- 4.14.1 (next) — 2025-04-27
- 5.0.0-alpha.20 (alpha) — 2023-08-02
- 5.0.0-alpha.2 (prealpha) — 2023-05-03
- 5.1.0-aardvark.next-20260925164249 — 2026-09-25
- 5.1.0-aardvark.next-20260922224416 — 2026-09-22
- 5.1.0-aardvark.next-20260919185130 — 2026-09-19
- 5.1.0-aardvark.next-20260918085327 — 2026-09-18
- 5.1.0-aardvark.next-20260910230054 — 2026-09-10
- 5.1.0-aardvark.next-20260907131448 — 2026-09-07
- 5.1.0-aardvark.next-20260902182429 — 2026-09-02
- 5.1.0-aardvark.next-20260902153400 — 2026-09-02
- … 205 more at https://npm.io/package/graphile-utils/versions
## README
# graphile-utils
[](https://github.com/sponsors/benjie)
[](http://discord.gg/graphile)
[](https://www.npmjs.com/package/graphile-utils)
[](https://bsky.app/profile/graphile.org)
[](https://fosstodon.org/@graphile)
This package contains helpers for building plugins for GraphQL schemas utilising
Graphile Build, such as the one produced by
[PostGraphile](https://postgraphile.org).
Documentation is currently available
[here](https://postgraphile.org/postgraphile/next/extending/).
PRs to improve documentation are always welcome!
## Crowd-funded open-source software
To help us develop this software sustainably, we ask all individuals and
businesses that use it to help support its ongoing maintenance and development
via sponsorship.
### [Click here to find out more about sponsors and sponsorship.](https://www.graphile.org/sponsor/)
And please give some love to our featured sponsors 🤩:
\* Sponsors the entire Graphile suite
### `extendSchema`
Docs: https://postgraphile.org/postgraphile/next/extend-schema
Enables you to add additonal types or extend existing types within your Graphile
Engine GraphQL schema.
```js
import { extendSchema } from 'graphile-utils';
const MySchemaExtensionPlugin =
extendSchema(
build => ({
typeDefs: /* GraphQL */ `...`,
objects: {...},
interfaces: {...},
unions: {...},
})
);
export default MySchemaExtensionPlugin;
```
e.g.:
```js
export default extendSchema((build) => {
const {
grafast: { constant },
} = build;
return {
typeDefs: /* GraphQL */ `
type Random {
float: Float!
number(min: Int!, max: Int!): Int!
}
extend type Query {
random: Random
}
`,
objects: {
Query: {
plans: {
random() {
return constant({});
},
},
},
Random: {
plans: {
float() {
return lambda(null, () => Math.random());
},
number(_parent, { $min, $max }) {
return lambda(
[$min, $max],
([min, max]) => min + Math.floor(Math.random() * (max - min + 1)),
);
},
},
},
},
};
});
```
#### `gql`
Similar to the default export from `graphql-tag`, this export can be used to
form tagged template literals that are useful when building schema extensions.
`gql` in `graphile-utils` differs from `graphql-tag` in a number of ways, most
notably: it can use interpolation to generate dynamically named fields and
types, and it can embed raw values using the `embed` helper.
```ts
extendSchema({ typeDefs: gql`...` });
```
#### `embed`
Used to wrap a value to be included in a `gql` AST, e.g. for use in GraphQL
directives.
```ts
extendSchema({ typeDefs: gql`...${embed(...)}...` });
```
### `changeNullability`
Docs: https://postgraphile.org/postgraphile/next/change-nullability
Use this plugin to override the nullability of fields in your GraphQL schema.
### `processSchema`
Docs: https://postgraphile.org/postgraphile/next/process-schema
Enables you to process the schema after it's built, e.g. print it to a file,
augment it with a third party library (e.g. graphql-shield), etc.
### `wrapPlans`
Docs: https://postgraphile.org/postgraphile/next/wrap-plans
Enables you to wrap the field plan resolvers in the generated Grafast schema,
allowing you to augment the way in which existing fields operate.
## Developing
### Testing
Make sure you first follow the instructions in the
[CONTRIBUTING.md file at the root of the repository](../../CONTRIBUTING.md),
then run the test with the following commands:
```bash
yarn build
yarn test
```
---
_Source: https://npm.io/package/graphile-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
