koa-graphqlCreate a GraphQL HTTP server with Koa.
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
: AGraphQLSchema
instance fromgraphql-js
. Aschema
must be provided. -
graphiql
: Iftrue
, presents GraphiQL when the GraphQL endpoint is loaded in a browser. We recommend that you setgraphiql
totrue
when your app is in development, because it's quite useful. You may or may not want it in production. Alternatively, instead oftrue
you can pass in an options object:-
defaultQuery
: An optional GraphQL string to use when no query is 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 therootValue
to thegraphql()
function fromgraphql-js/src/execute.js
. -
context
: A value to pass as thecontext
to thegraphql()
function fromgraphql-js/src/execute.js
. Ifcontext
is not provided, thectx
object is passed as the context. -
pretty
: Iftrue
, any JSON response will be pretty-printed. -
extensions
: An optional function for adding additional metadata to the GraphQL 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 to add development time metadata such as the runtime of a query or the amount of resources consumed. This may be an async function. The function is given one object as an argument:{ document, variables, operationName, result, context }
. -
validationRules
: Optional additional validation rules queries must satisfy in addition to those defined by the GraphQL spec. -
customValidateFn
: An optional function which will be used to validate instead of defaultvalidate
fromgraphql-js
. -
customExecuteFn
: An optional function which will be used to execute instead of defaultexecute
fromgraphql-js
. -
customFormatErrorFn
: An optional function which will be used to format any errors produced by fulfilling a GraphQL operation. If no function is provided, GraphQL's default spec-compliantformatError
function will be used. -
customParseFn
: An optional function which will be used to create a document instead of the defaultparse
fromgraphql-js
. -
formatError
: is deprecated and replaced bycustomFormatErrorFn
. It will be removed in version 1.0.0. -
fieldResolver
-
typeResolver
HTTP Usage
Once installed at a path, koa-graphql
will accept requests with the parameters:
-
query
: A string GraphQL document to be executed. -
variables
: The runtime values to use for any GraphQL query variables as a JSON object. -
operationName
: If the providedquery
contains multiple named operations, this specifies which operation should be executed. If not provided, a 400 error will be returned if thequery
contains multiple named operations. -
raw
: If thegraphiql
option is enabled and theraw
parameter is provided raw JSON will always be returned instead of GraphiQL even when loaded 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.body
value will be used. Use multer
or a similar middleware to add support for multipart/form-data
content, which may be useful for GraphQL mutations involving uploading files. See an example using multer.
If the POST body has not yet been parsed, koa-graphql will interpret it depending on the provided Content-Type header.
-
application/json
: the POST body will be parsed as a JSON object of parameters. -
application/x-www-form-urlencoded
: this POST body will be parsed as a url-encoded string of key-value pairs. -
application/graphql
: The POST body will be parsed as GraphQL query string, which provides thequery
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 the request 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 to a GraphQL query via a field in the response called "extensions"
. This is added by providing an extensions
function when using graphqlHTTP
. The function must return a JSON-serializable Object.
When called, this is provided an argument which you can use to get information about the GraphQL request:
{ document, variables, operationName, result, context }
This example illustrates adding the amount of time consumed by running the provided 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 your application any more secure. Nevertheless, disabling introspection is possible by utilizing the NoSchemaIntrospectionCustomRule
provided by the graphql-js package.
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 with the 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 to your custom theme and name
would be passed to the GraphiQL
react 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 as stack 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
Other relevant projects
Please checkout awesome-graphql.
Contributing
Welcome pull requests!
License
BSD-3-Clause