Create a GraphQL HTTP server with Koa.
Port from express-graphql
npm install --save koa-graphql
Mount koa-graphql
as a route handler:
const koa = require('koa');
const mount = require('koa-mount'); // [email protected]
const graphqlHTTP = require('koa-graphql');
const app = koa();
app.use(mount('/graphql', graphqlHTTP({
schema: MyGraphQLSchema,
graphiql: true
})));
app.listen(4000);
For Koa 2, use koa-convert to convert the middleware:
const koa = require('koa');
const mount = require('koa-mount'); // [email protected]
const convert = require('koa-convert');
const graphqlHTTP = require('koa-graphql');
const app = new Koa();
app.use(mount('/graphql', convert(graphqlHTTP({
schema: MyGraphQLSchema,
graphiql: true
}))));
For Koa 2 with koa-router@7
const koa = require('koa');
const Router = require('koa-router'); // [email protected]
const convert = require('koa-convert');
const graphqlHTTP = require('koa-graphql');
const app = new Koa();
const router = new Router();
router.all('/graphql', convert(graphqlHTTP({
schema: MyGraphQLSchema,
graphiql: true
})));
app.use(router.routes()).use(router.allowedMethods());
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.
The graphqlHTTP
function accepts the following options:
-
schema
: AGraphQLSchema
instance fromgraphql-js
. Aschema
must be provided. -
graphiql
: Iftrue
, presents GraphiQL when the route with a/graphiql
appended 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. -
rootValue
: A value to pass as therootValue
to thegraphql()
function fromgraphql-js
. -
context
: A value to pass as thecontext
to thegraphql()
function fromgraphql-js
. Ifcontext
is not provided, therequest
object is passed as the context. -
pretty
: Iftrue
, any JSON response will be pretty-printed. -
formatError
: 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. -
validationRules
: Optional additional validation rules queries must satisfy in addition to those defined by the GraphQL spec.
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.
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 = 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
}
}
}
});
During development, it's useful to get more information from errors, such as
stack traces. Providing a function to formatError
enables this:
formatError: error => ({
message: error.message,
locations: error.locations,
stack: error.stack
})
Please checkout awesome-graphql.
Welcome pull requests!
BSD-3-Clause