package
Simple, pluggable, zero-dependency, GraphQL over HTTP spec compliant server, client and audit suite.
npm install graphql-httpGitHub-flavored package documentation.
Across all versions, last 30 days.
9,022,088 in 30 days
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
404.5 kB
Includes dependencies.
Quickly check for compliance? Visit graphql-http.com!
Want a full-featured server? See the servers section!
Need subscriptions? Try graphql-ws or graphql-sse instead!
yarn add graphql-httpimport { GraphQLSchema, GraphQLObjectType, GraphQLString } from 'graphql';
/**
* Construct a GraphQL schema and define the necessary resolvers.
*
* type Query {
* hello: String
* }
*/
const schema = new GraphQLSchema({
query: new GraphQLObjectType({
name: 'Query',
fields: {
hello: {
type: GraphQLString,
resolve: () => 'world',
},
},
}),
});httpimport http from 'http';
import { createHandler } from 'graphql-http/lib/use/http';
import { schema } from './previous-step';
// Create the GraphQL over HTTP Node request handler
const handler = createHandler({ schema });
// Create a HTTP server using the listener on `/graphql`
const server = http.createServer((req, res) => {
if (req.url.startsWith('/graphql')) {
handler(req, res);
} else {
res.writeHead(404).end();
}
});
server.listen
http2Browsers might complain about self-signed SSL/TLS certificates. Help can be found on StackOverflow.
$ openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
-keyout localhost-privkey.pem -out localhost-cert.pemimport fs from 'fs';
import http2 from 'http2';
import { createHandler } from 'graphql-http/lib/use/http2';
import { schema } from './previous-step';
// Create the GraphQL over HTTP Node request handler
const handler = createHandler({ schema });
// Create a HTTP/2 server using the handler on `/graphql`
const server = http2.createSecureServer(
{
key: fs.readFileSync('localhost-privkey.pem'),
cert: fs.readFileSync('localhost-cert.pem'),
},
(req, res) => {
if (req.url.startsWith
expressimport express from 'express'; // yarn add express
import { createHandler } from 'graphql-http/lib/use/express';
import { schema } from './previous-step';
// Create an express instance serving all methods on `/graphql`
// where the GraphQL over HTTP express request handler is
const app = express();
app.all('/graphql', createHandler({ schema }));
app.listen({ port: 4000 });
console.log('Listening to port 4000');fastifyimport Fastify from 'fastify'; // yarn add fastify
import { createHandler } from 'graphql-http/lib/use/fastify';
import { schema } from './previous-step';
// Create a fastify instance serving all methods on `/graphql`
// where the GraphQL over HTTP fastify request handler is
const fastify = Fastify();
fastify.all('/graphql', createHandler({ schema }));
fastify.listen({ port: 4000 });
console.log('Listening to port 4000');Koaimport Koa from 'koa'; // yarn add koa
import mount from 'koa-mount'; // yarn add koa-mount
import { createHandler } from 'graphql-http/lib/use/koa';
import { schema } from './previous-step';
const app = new Koa();
app.use(mount('/graphql', createHandler({ schema })));
app.listen({ port: 4000 });
console.log('Listening to port 4000');uWebSockets.jsimport uWS from 'uWebSockets.js'; // yarn add uWebSockets.js@uNetworking/uWebSockets.js#<version>
import { createHandler } from 'graphql-http/lib/use/uWebSockets';
import { schema } from './previous-step';
uWS
.App()
.any('/graphql', createHandler({ schema }))
.listen(4000, () => {
console.log('Listening to port 4000');
});Denoimport { serve } from 'https://deno.land/std@0.151.0/http/server.ts';
import { createHandler } from 'https://esm.sh/graphql-http/lib/use/fetch';
import { schema } from './previous-step';
// Create the GraphQL over HTTP native fetch handler
const handler = createHandler({ schema });
// Start serving on `/graphql` using the handler
await serve(
(req: Request) => {
const [path, _search] = req.url.split('?');
if (path.endsWith('/graphql')) {
return handler(req);
} else {
return
Bunimport { createHandler } from 'graphql-http/lib/use/fetch'; // bun install graphql-http
import { schema } from './previous-step';
// Create the GraphQL over HTTP native fetch handler
const handler = createHandler({ schema });
// Start serving on `/graphql` using the handler
export default {
port: 4000, // Listening to port 4000
fetch(req) {
const [path, _search] = req.url.split('?');
if (path.endsWith('/graphql')) {
return handler(req);
} else {
return new Response(null, { status:
Netlify Functionsimport { createHandler } from 'graphql-http/lib/use/@netlify/functions'; // yarn add @netlify/functions
import { schema } from './previous-step';
// Create the GraphQL over HTTP native fetch handler
export const handler = createHandler({ schema });import { createClient } from 'graphql-http';
const client = createClient({
url: 'http://localhost:4000/graphql',
});
(async () => {
let cancel = () => {
/* abort the request if it is in-flight */
};
const result = await new Promise((resolve, reject) => {
let result;
cancel = client.subscribe(
{
query: '{ hello }',
},
{
next: (data)
Thanks to ruru, serving GraphiQL is as easy as running:
npx ruru -SP -p 4001 -e http://localhost:4000/graphqlOpen http://localhost:4001 in the browser to use it.
import { ExecutionResult } from 'graphql';
import { createClient, RequestParams } from 'graphql-http';
import { getSession } from './my-auth';
const client = createClient({
url: 'http://hey.there:4000/graphql',
headers: async () => {
const session = await getSession();
if (session) {
return {
Authorization: `Bearer ${session.token}`,
};
}
import { Observable } from 'relay-runtime';
// or
import { Observable } from '@apollo/client/core';
// or
import { Observable } from 'rxjs';
// or
import Observable from 'zen-observable';
// or any other lib which implements Observables as per the ECMAScript proposal: https://github.com/tc39/proposal-observable
import { createClient } from 'graphql-http';
import { getSession } from './my-auth';
import { GraphQLError } from 'graphql';
import {
Network,
Observable,
RequestParameters,
Variables,
} from 'relay-runtime';
import { createClient } from 'graphql-http';
import { getSession } from './my-auth';
const client = createClient({
url: 'http://i.love:4000/graphql',
headers: async
import {
ApolloLink,
Operation,
FetchResult,
Observable,
} from '@apollo/client/core';
import { print, GraphQLError } from 'graphql';
import { createClient, ClientOptions, Client } from 'graphql-http';
import { getSession } from './my-auth';
class HTTPLink extends ApolloLink {
private client: Client;
import { createClient, NetworkError } from 'graphql-http';
const client = createClient({
url: 'http://unstable.service:4000/graphql',
shouldRetry: async (err: NetworkError, retries: number) => {
if (retries > 3) {
// max 3 retries and then report service down
return false;
}
// try again when service unavailable, could be temporary
if (err.response?.status === 503) {
// wait one second (you can alternatively time the promise resolution to your preference)
await
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<title>GraphQL over HTTP</title>
<script
type="text/javascript"
src="https://unpkg.com/graphql-http/umd/graphql-http.min.js"
></script>
</head>
<body>
<script type="text/javascript">
const client =
const fetch = require('node-fetch'); // yarn add node-fetch
const { AbortController } = require('node-abort-controller'); // (node < v15) yarn add node-abort-controller
const { createClient } = require('graphql-http');
const client = createClient({
url: 'http://no.browser:4000/graphql',
fetchFn: fetch,
abortControllerImpl: AbortController, // node < v15
});
// consider other recipes for usage inspirationimport { createClient } from 'https://esm.sh/graphql-http';
const client = createClient({
url: 'http://deno.earth:4000/graphql',
});
// consider other recipes for usage inspirationimport { createClient } from 'graphql-http'; // bun install graphql-http
const client = createClient({
url: 'http://bun.bread:4000/graphql',
});
// consider other recipes for usage inspirationimport express from 'express';
import { schema } from './my-graphql-schema';
-import { graphqlHTTP } from 'express-graphql';
+import { createHandler } from 'graphql-http/lib/use/express';
const app = express();
app.use(
'/graphql',
- graphqlHTTP({ schema }),
+ createHandler({ schema }),
);
app.listen(4000);Authenticate the user within graphql-http during GraphQL execution context assembly. This is a approach is less safe compared to early authentication (see early authentication in Node) because some GraphQL preparations or operations are executed even if the user is not unauthorized.
import { createHandler } from 'graphql-http';
import {
schema,
getUserFromCookies,
getUserFromAuthorizationHeader,
} from './my-graphql';
const handler = createHandler({
schema,
context: async (req) => {
// process token, authenticate user and attach it to your graphql context
const userId = await getUserFromCookies(req.headers.cookie);
import { createHandler } from 'graphql-http';
import { schema, getDynamicContext } from './my-graphql';
const handler = createHandler({
schema,
context: async (req, args) => {
return getDynamicContext(req, args);
},
// or static context by supplying the value directly
});import { parse } from 'graphql';
import { createHandler } from 'graphql-http';
import { getSchemaForRequest, myValidationRules } from './my-graphql';
const handler = createHandler({
onSubscribe: async (req, params) => {
const schema = await getSchemaForRequest(req);
const args = {
schema,
operationName: params.operationName,
document: parse(params.query),
variableValues: params.variables,
};
return
Authenticate the user early, before reaching graphql-http. This is the recommended approach because no GraphQL preparations or operations are executed if the user is not authorized.
import { createHandler } from 'graphql-http';
import {
schema,
getUserFromCookies,
getUserFromAuthorizationHeader,
} from './my-graphql';
const handler = createHandler({
schema,
context: async (req) => {
// user is authenticated early (see below), simply attach it to the graphql context
return { userId: req.raw.userId };
},
});
const server = http.createServer(
import http from 'http';
import { createHandler } from 'graphql-http/lib/use/http';
import processRequest from 'graphql-upload/processRequest.mjs'; // yarn add graphql-upload
import { schema } from './my-graphql';
const handler = createHandler({
import express from 'express'; // yarn add express
import { createHandler } from 'graphql-http/lib/use/express';
import processRequest from 'graphql-upload/processRequest.mjs'; // yarn add graphql-upload
import { schema } from './my-graphql';
const app = express
import { fetch } from '@whatwg-node/fetch';
import { serverAudits } from 'graphql-http';
for (const audit of serverAudits({
url: 'http://localhost:4000/graphql',
fetchFn: fetch,
})) {
test(audit.name, async () => {
const result = await audit.fn();
if (result.status ===
import { serverAudits } from 'npm:graphql-http';
for (const audit of serverAudits({
url: 'http://localhost:4000/graphql',
fetchFn: fetch,
})) {
Deno.test(audit.name, async () => {
const result = await audit.fn();
if (result.status === 'error') {
throw result.reason;
This is the official GraphQL over HTTP spec reference implementation and as such follows the specification strictly without any additional features (like playgrounds or GUIs, file uploads, @stream/@defer directives and subscriptions).
Having said this, graphql-http is mostly aimed for library authors and simple server setups, where the requirements are exact to what the aforementioned spec offers.
If you want a feature-full server with bleeding edge technologies, you're recommended to use one of the following servers.
Their compliance with the GraphQL over HTTP spec is checked automatically and updated regularly.
Check the docs folder out for TypeDoc generated documentation.
Inspect audits of other implementations in the implementations folder. Adding your implementation is very welcome, see how!
File a bug, contribute with code, or improve documentation? Read more in CONTRIBUTING.md.
If your company benefits from GraphQL and you would like to provide essential financial support for the systems and people that power our community, please also consider membership in the GraphQL Foundation.
leebyron
lee@leebyron.com
Put the above contents in a file and run it with deno test --allow-net.
| graph-client | ✅ Compliant |
| graphql-helix | ✅ Compliant |
| graphql-yoga | ✅ Compliant |
| hotchocolate | ✅ Compliant |
| lighthouse | ✅ Compliant |
| pioneer | ✅ Compliant |
| postgraphile | ✅ Compliant |