Server plugins

NOTE: This page relates to changing how the PostGraphile HTTP server (Grafserv) and other non-schema concerns work. If you're instead looking to change the generated GraphQL schema (e.g. to add fields or types), see Schema Plugins.

In addition to the Graphile Build plugin system which builds the GraphQL schema in PostGraphile, PostGraphile also has a plugin system for the CLI and web layer. Thanks to graphile-config, this now uses the same plugin system, just different scopes.

Currently these scopes are undocumented, so here's some examples

Customizing Ruru's title:

function makeRuruTitlePlugin(title: string): GraphileConfig.Plugin {
  return {
    name: "RuruTitlePlugin",
    version: "0.0.0",

    grafserv: {
      middleware: {
        ruruHTMLParts(next, event) {
          const { htmlParts, request } = event;
          htmlParts.titleTag = `<title>${escapeHTML(
            title + " | " + request.getHeader("host"),
          )}</title>`;
          return next();
        },
      },
    },
  };
}

Manipulating the request body

For example you might want to implement a plugin where you pass only the operation name (not the full document) and have the server populate the document by looking up the operation name.

tip

This is purely for demonstration of the plugin API, you should not use this plugin! Instead, consider the @grafserv/persisted module (which uses the same middleware).

import { SafeError } from "grafast";

const documents = Object.assign(Object.create(null), {
  QueryName: `query QueryName { __typename }`,
  WhoAmI: `query WhoAmI { currentUser { name } }`,
  CreatePost: `mutation CreatePost($input: CreatePostInput!) { createPost(input: $input) { post { id title } } }`,
});

export const QueryByNamePlugin: GraphileConfig.Plugin = {
  name: "QueryByNamePlugin",
  description: "Only specify the query name and the query will be populated",
  version,

  grafserv: {
    middleware: {
      processGraphQLRequestBody(next, event) {
        const { body } = event;
        const document = documents[body.id];
        if (!document) {
          throw new SafeError(
            `QueryByNamePlugin couldn't find query '${body.id}'`,
            { statusCode: 400 },
          );
        } else {
          body.query = document;
        }
        return next();
      },
    },
  },
};

If you need help writing your own PostGraphile server plugins, ask in #help-and-support in our Discord chat.