Create a GraphQL HTTP server with koa v2. it's ported from express-graphql. koa-graphql-next have the same api with express-graphql, and well tested like express-graphql,that's mean,and could be try to using in product currently.
- only supported koa v2
- add url to options,and default url is '/graphql'
- using jest and supertest,instead of mocha in express-graphql.all test from express-graphql (now 64 tests),have been rewrited and passed.
- ported from express-graphql,for the code,"line by line",and rewrites all the test of express-graphql,so fix many bug founded in tests. but,thanks for the author of these project: koa-graphql by chentsulin graffiti it proveder a middleware for koa v1. koa-graphql by Arch-Mage
- for the detail of usage,could read the test,for example how to upload files with graphql.
npm install --save koa-graphql-next
Then use koa-graphql-next
at any point as a middleware with koa@next:
import graphqlHTTP from 'koa-graphql-next';
const app = new koa();
app.use( graphqlHTTP({
schema: MyGraphQLSchema,
graphiql: true
}));
app.listen(3000);
The graphqlHTTP
function accepts the following options:
-
schema
: AGraphQLSchema
instance fromgraphql-js
. Aschema
must be provided. -
context
: A value to pass as thecontext
to thegraphql()
function fromgraphql-js
. -
rootValue
: A value to pass as therootValue
to thegraphql()
function fromgraphql-js
. -
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. -
graphiql
: Iftrue
, may present GraphiQL when loaded directly from a browser (a useful tool for debugging and exploration). -
url
: added in koa-graphql-next,An optional string for the query url. default value is '/graphql'.
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
})
Once installed at a path, koa-graphql-next
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 ctx.request.body
value will be used. Use [koa-multer
][] or a similar middleware to add support
for multipart/form-data
content, which may be useful for GraphQL mutations
involving uploading files.
If the POST body has not yet been parsed, koa-graphql-next 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.