Usage
Grafserv supports many different servers, and because each server is different,
each has their own entrypoint, e.g. grafserv/node for the Node.js HTTP server
or grafserv/express/v4 for Express v4.
Creating serv instance
Generally you import the grafserv function from the relevant entrypoint for
your server of choice and then create an instance, called serv, by passing
the preset and the GraphQL schema to use:
import { grafserv } from "grafserv/path/to/adaptor";
import preset from "./graphile.config";
import schema from "./schema";
const serv = grafserv({ preset, schema });
The serv instance will have a number of methods on it, including
methods specific to integrating it with your framework of choice. The methods
available will differ for each server, but common methods are documented
below.
Preset
The preset is your configuration object, see Configuration. To
use the defaults, it can be a simple empty object ({}).
Schema
The schema can be any valid GraphQL.js schema, but for maximal benefit it should be a Grafast-capable schema. For details on creating a Grafast schema, see Grafast.
If a schema is not available then passing either null or a promise is
acceptable.
Integrating with your server
Please see the documentation for your specific server adaptor, but for servers
that operate on a middleware basis this is typically serv.addTo(app) (which
allows registering multiple route handlers); e.g. for Express:
import express from "express";
import { createServer } from "node:http";
const app = express();
const server = createServer(app);
await serv.addTo(app, server);
server.listen(preset.grafserv?.port ?? 5678);
Other servers such as Lambda and
Next.js may use
different APIs, such as serv.createGraphQLHandler().
There is little value in Grafserv reimplementing every non-GraphQL concern
your server may have, so instead it leans on the ecosystem of your chosen server
to handle things like compression, rate limits, sessions, cookies, etc. For
example, to compress your responses you'd need to use a module like
compression
for Express, koa-compress for
Koa, or @fastify/compress
for Fastify.
Common methods
serv.release()
Releases any resources created by the instance; no further requests should be handled (though currently active requests will be allowed to complete).
// TODO: consider terminating subscriptions or other long-lived things.
serv.onRelease(cb)
Adds cb to the list of callbacks to be called when the server is released;
useful for releasing resources you created only for the server. Callbacks will
be called in reverse order that they were added.
serv.setSchema(newSchema)
Replaces the schema to use for future requests (currently active requests are unaffected) - this is primarily used for "watch" mode.
serv.setPreset(newPreset)
Replaces the config to use for future requests (currently active requests are unaffected) - this is primarily used for "watch" mode. Note that certain configuration changes might not be reflected by certain servers until a restart.
serv.getSchema()
Returns either the GraphQL schema that is currently in use, or a promise to the same.
serv.getPreset()
Returns the resolved graphile-config preset that is currently in use.