graphile-utils

This package contains helpers for building plugins for GraphQL schemas utilising Graphile Build, such as the one produced by PostGraphile.

Documentation is currently available here.

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.

And please give some love to our featured sponsors 🤩:

Steelhead *

* 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.

import { extendSchema } from 'graphile-utils';

const MySchemaExtensionPlugin =
  extendSchema(
    build => ({
      typeDefs: /* GraphQL */ `...`,
      objects: {...},
      interfaces: {...},
      unions: {...},
    })
  );

export default MySchemaExtensionPlugin;

e.g.:

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.

extendSchema({ typeDefs: gql`...` });

embed

Used to wrap a value to be included in a gql AST, e.g. for use in GraphQL directives.

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, then run the test with the following commands:

yarn build
yarn test