@as-integrations/fastify

Apollo Server Integration for Fastify

Introduction

An Apollo Server integration for use with Fastify.

This is a simple package that easily allows you to connect your own Fastify server implementation to an Apollo Server instance.

Requirements

• Node.js v14 or later
• Fastify v4.4 or later
• GraphQL.js v16 or later
• Apollo Server v4 or later

Installation

npm install @as-integrations/fastify @apollo/server graphql fastify

Usage

Setup Fastify & Apollo Server like you usually would and then connect the two by using the fastifyApollo plugin:

import Fastify from "fastify";
import { ApolloServer, BaseContext } from "@apollo/server";
import fastifyApollo, { fastifyApolloDrainPlugin } from "@as-integrations/fastify";
// ...

const fastify = Fastify();

const apollo = new ApolloServer<BaseContext>({
  typeDefs,
  resolvers,
  plugins: [fastifyApolloDrainPlugin(fastify)],
});

await apollo.start();

// ...

await fastify.register(fastifyApollo(apollo));

Note: You must call and await apollo.start() before using using the intergration.

Alternatively you can use the exported function fastifyApolloHandler which can be passed into any Fastify route handler. This allows you to explicitly set all routing options like the URL path and accepted methods.

Examples shown below:

import { fastifyApolloHandler } from "@as-integrations/fastify";

// ... setup Fastify & Apollo

fastify.post("/graphql", fastifyApolloHandler(apollo));
// OR
fastify.get("/api", fastifyApolloHandler(apollo));
// OR
fastify.route({
  url: "/graphql",
  method: ["POST", "OPTIONS"],
  handler: fastifyApolloHandler(apollo),
});

Please see the example.

Context

Apollo Server v4 has moved context setup outside of the ApolloServer constructor.

Define you're own context function and pass it in to the context option.

For example:

import { ApolloServer } from "@apollo/server";

import fastifyApollo, {
  fastifyApolloHandler,
  ApolloFastifyContextFunction,
} from "@as-integrations/fastify";
// ...

interface MyContext {
  authorization: JWTPayload | false;
}

const apollo = new ApolloServer<MyContext>(...);

const myContextFunction: ApolloFastifyContextFunction<MyContext> = async request => ({
  authorization: await isAuthorized(request.headers.authorization),
});

await fastify.register(fastifyApollo(apollo), {
  context: myContextFunction,
});

// OR

await fastify.post("/graphql", fastifyApolloHandler(apollo, {
  context: myContextFunction,
}));

API

All options and generics are optional other than passing in the ApolloServer instance.

fastifyApollo

function fastifyApollo<Context extends BaseContext = BaseContext>(
  apollo: ApolloServer<Context>,
): FastifyPluginAsync<ApolloFastifyPluginOptions<Context>>;

fastifyApolloHandler

function fastifyApolloHandler<Context extends BaseContext = BaseContext>(
  apollo: ApolloServer<Context>,
  options?: ApolloFastifyHandlerOptions<Context>,
): RouteHandlerMethod;

ApolloFastifyContextFunction

type ApolloFastifyContextFunction<Context> = (
  request: FastifyRequest,
  reply: FastifyReply,
) => Promise<Context>;

ApolloFastifyHandlerOptions:

interface ApolloFastifyHandlerOptions<Context extends BaseContext = BaseContext> {
  context?: ApolloFastifyContextFunction<Context>; // default: async () => ({})
}

ApolloFastifyPluginOptions:

interface ApolloFastifyPluginOptions<Context extends BaseContext = BaseContext>
  extends ApolloFastifyHandlerOptions<Context> {
  path?: string; // default: "/graphql"
  method?: HTTPMethod | HTTPMethod[]; // default: ["GET", "POST", "OPTIONS"]
}

HTTPMethod is exported from Fastify.

HTTPS/HTTP2

All functions and types optionally allow you to pass in or infer a Server type from Fastify.

Node.JS v14

Please pass in forceCloseConnections: true to Fastify in combintation with fastifyApolloDrainPlugin to correctly shutdown you're server on close and not hang incoming requests.

Contributors

• Oliver Plummer (olyop)
• Trevor Scheer (trevor-scheer)

Changelog

v1.1.0

• PACKAGE: Remove graphql as a peer dependency #50.
• PACKAGE: Update fastify-plugin metadata #58.
• PACKAGE: Remove unnecessary String.toLowerCase call #59.
• DEV: Update Readme.
• DEV: Update example to include @as-intergrations/fastify instead of a relative import.
• DEV: Add changelog.
• DEV: Removed unused devDependencies #57.