GraphQL Koa Middleware

Create a GraphQL HTTP server with Koa.

Port from express-graphql.

Installation

npm install --save koa-graphql

Usage

Mount koa-graphql as a route handler:

const Koa = require('koa');
const mount = require('koa-mount');
const graphqlHTTP = require('koa-graphql');

const app = new Koa();

app.use(
  mount(
    '/graphql',
    graphqlHTTP({
      schema: MyGraphQLSchema,
      graphiql: true,
    }),
  ),
);

app.listen(4000);

With koa-router@7

const Koa = require('koa');
const Router = require('koa-router'); // koa-router@7.x
const graphqlHTTP = require('koa-graphql');

const app = new Koa();
const router = new Router();

router.all(
  '/graphql',
  graphqlHTTP({
    schema: MyGraphQLSchema,
    graphiql: true,
  }),
);

app.use(router.routes()).use(router.allowedMethods());

For Koa 1, use koa-convert to convert the middleware:

const koa = require('koa');
const mount = require('koa-mount'); // koa-mount@1.x
const convert = require('koa-convert');
const graphqlHTTP = require('koa-graphql');

const app = koa();

app.use(
  mount(
    '/graphql',
    convert.back(
      graphqlHTTP({
        schema: MyGraphQLSchema,
        graphiql: true,
      }),
    ),
  ),
);

NOTE: Below is a copy from express-graphql's README. In this time I implemented almost same api, but it may be changed as time goes on.

Options

The graphqlHTTP function accepts the following options:

• schema: A GraphQLSchema instance from graphql-js.A schema must be provided.

• graphiql: If true, presents GraphiQL when the GraphQL endpoint isloaded in a browser. We recommend that you set graphiql to true when yourapp is in development, because it's quite useful. You may or may not want itin production.Alternatively, instead of true you can pass in an options object:

  • defaultQuery: An optional GraphQL string to use when no queryis provided and no stored query exists from a previous session.If undefined is provided, GraphiQL will use its own default query.
  • editorTheme: By passing an object you may change the theme of GraphiQL.Details are below in the Custom GraphiQL themes section.

• rootValue: A value to pass as the rootValue to the graphql()function from graphql-js/src/execute.js.

• context: A value to pass as the context to the graphql()function from graphql-js/src/execute.js. If context is not provided, thectx object is passed as the context.

• pretty: If true, any JSON response will be pretty-printed.

• extensions: An optional function for adding additional metadata to theGraphQL response as a key-value object. The result will be added to the"extensions" field in the resulting JSON. This is often a useful place toadd development time metadata such as the runtime of a query or the amountof resources consumed. This may be an async function. The function isgiven one object as an argument: { document, variables, operationName, result, context }.

• validationRules: Optional additional validation rules queries mustsatisfy in addition to those defined by the GraphQL spec.

• customValidateFn: An optional function which will be used to validateinstead of default validate from graphql-js.

• customExecuteFn: An optional function which will be used to executeinstead of default execute from graphql-js.

• customFormatErrorFn: An optional function which will be used to format anyerrors produced by fulfilling a GraphQL operation. If no function isprovided, GraphQL's default spec-compliant formatError function will be used.

• customParseFn: An optional function which will be used to create a documentinstead of the default parse from graphql-js.

• formatError: is deprecated and replaced by customFormatErrorFn. It will beremoved in version 1.0.0.

• fieldResolver

• typeResolver

HTTP Usage

Once installed at a path, koa-graphql will accept requests withthe parameters:

• query: A string GraphQL document to be executed.

• variables: The runtime values to use for any GraphQL query variablesas a JSON object.

• operationName: If the provided query contains multiple namedoperations, this specifies which operation should be executed. If notprovided, a 400 error will be returned if the query contains multiplenamed operations.

• raw: If the graphiql option is enabled and the raw parameter isprovided raw JSON will always be returned instead of GraphiQL even whenloaded from a browser.

GraphQL will first look for each parameter in the URL's query-string:

/graphql?query=query+getUser($id:ID){user(id:$id){name}}&variables={"id":"4"}

If not found in the query-string, it will look in the POST request body.

If a previous middleware has already parsed the POST body, the request.bodyvalue will be used. Use multer or a similar middleware to add supportfor multipart/form-data content, which may be useful for GraphQL mutationsinvolving uploading files. See an example using multer.

If the POST body has not yet been parsed, koa-graphql will interpret itdepending on the provided Content-Type header.

• application/json: the POST body will be parsed as a JSONobject of parameters.

• application/x-www-form-urlencoded: this POST body will beparsed as a url-encoded string of key-value pairs.

• application/graphql: The POST body will be parsed as GraphQLquery string, which provides the query parameter.

Combining with Other koa Middleware

By default, the koa request is passed as the GraphQL context.Since most koa middleware operates by adding extra data to therequest object, this means you can use most koa middleware just by inserting it before graphqlHTTP is mounted. This covers scenarios such as authenticating the user, handling file uploads, or mounting GraphQL on a dynamic endpoint.

This example uses koa-session to provide GraphQL with the currently logged-in session.

const Koa = require('koa');
const mount = require('koa-mount');
const session = require('koa-session');
const graphqlHTTP = require('koa-graphql');

const app = new Koa();
app.keys = ['some secret hurr'];
app.use(session(app));
app.use(function* (next) {
  this.session.id = 'me';
  yield next;
});

app.use(
  mount(
    '/graphql',
    graphqlHTTP({
      schema: MySessionAwareGraphQLSchema,
      graphiql: true,
    }),
  ),
);

Then in your type definitions, you can access the ctx via the third "context" argument in your resolve function:

new GraphQLObjectType({
  name: 'MyType',
  fields: {
    myField: {
      type: GraphQLString,
      resolve(parentValue, args, ctx) {
        // use `ctx.session` here
      },
    },
  },
});

Providing Extensions

The GraphQL response allows for adding additional information in a response toa GraphQL query via a field in the response called "extensions". This is addedby providing an extensions function when using graphqlHTTP. The functionmust return a JSON-serializable Object.

When called, this is provided an argument which you can use to get informationabout the GraphQL request:

{ document, variables, operationName, result, context }

This example illustrates adding the amount of time consumed by running theprovided query, which could perhaps be used by your development tools.

const graphqlHTTP = require('koa-graphql');

const app = new Koa();

app.keys = ['some secret hurr'];
app.use(session(app));

const extensions = ({
  document,
  variables,
  operationName,
  result,
  context,
}) => {
  return {
    runTime: Date.now() - context.startTime,
  };
};

app.use(
  mount(
    '/graphql',
    graphqlHTTP((request) => {
      return {
        schema: MyGraphQLSchema,
        context: { startTime: Date.now() },
        graphiql: true,
        extensions,
      };
    }),
  ),
);

When querying this endpoint, it would include this information in the result,for example:

{
  "data": { ... }
  "extensions": {
    "runTime": 135
  }
}

Additional Validation Rules

GraphQL's validation phase checks the query to ensure that it can be successfully executed against the schema. The validationRules option allows for additional rules to be run during this phase. Rules are applied to each node in an AST representing the query using the Visitor pattern.

A validation rule is a function which returns a visitor for one or more node Types. Below is an example of a validation preventing the specific field name metadata from being queried. For more examples, see the specifiedRules in the graphql-js package.

import { GraphQLError } from 'graphql';

export function DisallowMetadataQueries(context) {
  return {
    Field(node) {
      const fieldName = node.name.value;

      if (fieldName === 'metadata') {
        context.reportError(
          new GraphQLError(
            `Validation: Requesting the field ${fieldName} is not allowed`,
          ),
        );
      }
    },
  };
}

Disabling introspection

Disabling introspection does not reflect best practices and does not necessarily make yourapplication any more secure. Nevertheless, disabling introspection is possible by utilizing theNoSchemaIntrospectionCustomRule provided by the graphql-jspackage.

import { NoSchemaIntrospectionCustomRule } from 'graphql';

app.use(
  '/graphql',
  graphqlHTTP((request) => {
    return {
      schema: MyGraphQLSchema,
      validationRules: [NoSchemaIntrospectionCustomRule],
    };
  }),
);

Custom GraphiQL themes

To use custom GraphiQL theme you should pass to graphiql option an object withthe property editorTheme. It could be a string with the name of a theme from CodeMirror

router.all(
  '/graphql',
  graphqlHTTP({
    schema: MyGraphQLSchema,
    graphiql: {
      editorTheme: 'blackboard',
    },
  }),
);

List of available CodeMirror themas

or an object with url and name properties where url should lead toyour custom theme and name would be passed to the GraphiQLreact element on creation as the editorTheme property

router.all(
  '/graphql',
  graphqlHTTP({
    schema: MyGraphQLSchema,
    graphiql: {
      editorTheme: {
        name: 'blackboard',
        url: 'https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.53.2/theme/erlang-dark.css',
      },
    },
  }),
);

For details see the GraphiQL spec

Additional Validation Rules

GraphQL's validation phase checks the query to ensure that it can be successfully executed against the schema. The validationRules option allows for additional rules to be run during this phase. Rules are applied to each node in an AST representing the query using the Visitor pattern.

A validation rule is a function which returns a visitor for one or more node Types. Below is an example of a validation preventing the specific fieldname metadata from being queried. For more examples see the specifiedRules in the graphql-js package.

import { GraphQLError } from 'graphql';

export function DisallowMetadataQueries(context) {
  return {
    Field(node) {
      const fieldName = node.name.value;

      if (fieldName === 'metadata') {
        context.reportError(
          new GraphQLError(
            `Validation: Requesting the field ${fieldName} is not allowed`,
          ),
        );
      }
    },
  };
}

Debugging Tips

During development, it's useful to get more information from errors, such asstack traces. Providing a function to customFormatErrorFn enables this:

customFormatErrorFn: (error, ctx) => ({
  message: error.message,
  locations: error.locations,
  stack: error.stack ? error.stack.split('\n') : [],
  path: error.path,
});

Examples

• koa-graphql-relay-example
• tests

Other relevant projects

Please checkout awesome-graphql.

Contributing

Welcome pull requests!

License

BSD-3-Clause