On this page

GraphQL-Yoga

GraphQL Yoga is the cross-JavaScript runtime GraphQL server maintained by The Guild. We provide an easy to use plugin for GraphQL Yoga to integrate with Hive.

Installation

npm i @graphql-hive/yoga

The @graphql-hive/yoga package exports a Yoga plugin, that can be used directly with GraphQL-Yoga.

Configuration

A full configuration guide can be found in the “Configuration” page.

Integration Guide

Publishing Schemas

Please use the Hive CLI to publish your GraphQL schema. Follow the CI/CD instructions for automating the process.

Usage Reporting

GraphQL over HTTP (default)

You can send usage reporting to Hive registry by using the usage section of the configuration:

import { createServer } from "node:http";
import { createYoga } from "graphql-yoga";
import { useHive } from "@graphql-hive/yoga";
import { schema } from "./schema";

const yoga = createYoga({
  schema,
  plugins: [
    useHive({
      enabled: true, // Enable/Disable Hive Client
      token: "YOUR-TOKEN",
      // Collects and send usage reporting based on executed operations
      usage: {
        target: "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>",
      },
    }),
  ],
});

const server = createServer(yoga);

server.listen(4000, () => {
  console.info("Server is running on http://localhost:4000/graphql");
});

Cloudflare Workers

To use Hive with Cloudflare Workers, you can use GraphQL Yoga (as shown below) or use the generic Hive client with your own GraphQL server implementation.

Here’s an example of how to use Hive with GraphQL Yoga on Cloudflare Workers:

import { createYoga } from "graphql-yoga";
import { createHive, useHive } from "@graphql-hive/yoga";

export default {
  async fetch(request, env, ctx) {
    const hive = createHive({
      enabled: true, // Enable/Disable Hive Client
      token: "YOUR-TOKEN",
      usage: {
        target: "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>",
      },
      autoDispose: false,
    });

    const yoga = createYoga({
      plugins: [useHive(hive)],
    });

    const response = await yoga.fetch(request, env, ctx);
    ctx.waitUntil(hive.dispose());
    return response;
  },
};
Client Information

You can associate a client name and version with any operation reported to Hive, by sending the client information HTTP headers for requests sent to your GraphQL Yoga server. Those are x-graphql-client-name (or graphql-client-name) and x-graphql-client-version (or graphql-client-version).

Example HTTP Request with client headers
curl \
  -H "x-graphql-client-name: my-client" \
  -H "x-graphql-client-version: 1.0.0" \
  -H "content-type: application/json" \
  -H "accept: application/json" \
  -X POST \
  "http://localhost:4000/graphql" \
  -d '{"query":"{ hello }"}'

GraphQL over SSE

GraphQL over SSE is a popular protocol for executing GraphQL Subscription (and also Mutation and Query) operations.

No additional configuration is required for sending usage reporting to Hive when using the graphql-sse plugin. Just add the SSE plugin to your Yoga server and the usage reporting will be sent automatically.

SSE HTTP Request Client info
import { createServer } from "node:http";
import { createYoga, type YogaInitialContext } from "graphql-yoga";
import { useHive } from "@graphql-hive/yoga";
import { useGraphQLSSE } from "@graphql-yoga/plugin-graphql-sse";
import { schema } from "./schema";

const yoga = createYoga({
  schema,
  plugins: [
    useGraphQLSSE(),
    useHive({
      enabled: true,
      token: "YOUR-TOKEN",
      usage: {
        target: "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>",
      },
    }),
  ],
});

const server = createServer(yoga);

server.listen(4000, () => {
  console.info("Server is running on http://localhost:4000/graphql");
});
Client Information

The same rules apply for any other HTTP client, such as Apollo Client, Relay, or any other HTTP. Just forward send the headers to your server.

SSE HTTP Request with headers
curl \
  -H "x-graphql-client-name: my-client" \
  -H "x-graphql-client-version: 1.0.0" \
  -H "content-type: text/event-stream" \
  -H "accept: text/event-stream" \
  -X GET \
  "http://localhost:4000/graphql/stream?query={__typename}"

GraphQL over WebSocket

GraphQL over WebSocket is a popular protocol for executing GraphQL Subscription (and also Mutation and Query) operations.

Use the following example for sending usage reporting to Hive with GraphQL Yoga and graphql-ws (using the official recipe).

GraphQL Yoga HTTP and WebSocket Setup
import { createServer } from "node:http";
import { useServer } from "graphql-ws/lib/use/ws";
import { createYoga } from "graphql-yoga";
import { WebSocketServer } from "ws";
import { useHive } from "@graphql-hive/yoga";
import { schema } from "./schema";

const yoga = createYoga({
  schema,
  graphiql: {
    subscriptionsProtocol: "WS",
  },
  plugins: [
    useHive({
      enabled: true,
      token: "YOUR-TOKEN",
      usage: {
        target: "<YOUR_ORGANIZATION>/<YOUR_PROJECT>/<YOUR_TARGET>",
      },
    }),
  ],
});

const httpServer = createServer(yoga);
const wsServer = new WebSocketServer({
  server: httpServer,
  path: yoga.graphqlEndpoint,
});

useServer(
  {
    execute: (args: any) => args.rootValue.execute(args),
    subscribe: (args: any) => args.rootValue.subscribe(args),
    onSubscribe: async (ctx, msg) => {
      const { schema, execute, subscribe, contextFactory, parse, validate } =
        yoga.getEnveloped({
          ...ctx,
          req: ctx.extra.request,
          socket: ctx.extra.socket,
          params: msg.payload,
        });

      const args = {
        schema,
        operationName: msg.payload.operationName,
        document: parse(msg.payload.query),
        variableValues: msg.payload.variables,
        contextValue: await contextFactory(),
        rootValue: {
          execute,
          subscribe,
        },
      };

      const errors = validate(args.schema, args.document);
      if (errors.length) return errors;
      return args;
    },
  },
  wsServer,
);

httpServer.listen(4000, () => {
  console.log("Server is running on port 4000");
});
Client Information

When using the graphql-ws client, you can use the connectionParams object to forward the client information to the server.

GraphQL over WebSocket client configuration
import { createClient } from "graphql-ws";

const client = createClient({
  url: `ws://localhost:400/graphql`,
  connectionParams: {
    client: {
      name: "my-client",
      version: "1.0.0",
    },
  },
});

Additional Resources