DocumentationCLI/API ReferenceHive Gateway Configuration

Hive Gateway Configuration Reference

An overview of all the configuration options for the Hive Gateway, both CLI and Progammatic Usage.

Default CLI Config Files

The following list of files are loaded by default, sorted by priority:

  • gateway.config.ts (recommended)
  • gateway.config.mts
  • gateway.config.cts
  • gateway.config.js
  • gateway.config.mjs
  • gateway.config.cjs

Both TypeScript (*.ts) and JavaScript (*.js) config filetypes are supported.

Supergraph Related

supergraph

You can provide GraphQLSchema, DocumentNode which has the AST of the supergraph or string which is the SDL representation of the supergraph.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  supergraph: './supergraph.graphql',
  // or
  supergraph: 'https://example.com/supergraph.graphql',
  // or you can provide a function that returns a promise of the schema
  supergraph: () =>
    fetch('https://example.com/unified.graphql', {
      headers: {
        Authorization: 'Bearer token'
      }
    }).then(res => res.text())
})

For Hive Registry and Apollo GraphOS, you probably don’t need to provide the supergraph option.

Polling

Let’s say you have a source that can be changed after a while, it can be a CDN, schema registry or a local file. By enabling this option, Hive Gateway can poll the source and update the schema automatically using the set interval.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  pollingInterval: 5_000 // Polling interval in milliseconds
})

When running the Hive Gateway serverless on the edge and having provided a cache storage, the remote schema will be stored in the provided cache and the pollingInterval option is used as a TTL.

worker.ts
import { createGatewayRuntime } from '@graphql-hive/gateway-runtime'
import CloudflareKVCacheStorage from '@graphql-mesh/cache-cfw-kv'
import supergraph from './my-remote-supergraph-config'
 
export default {
  fetch(request, env, ctx) {
    const gateway = createGatewayRuntime({
      supergraph,
      pollingInterval: 5_000, // TTL in milliseconds of the remote supergraph
      transports: { http },
      cache: new CloudflareKVCacheStorage({
        logger,
        namespace: env.NAMESPACE
      })
    })
    ctx.waitUntil(gateway[Symbol.asyncDispose]())
    return gateway(request, env, ctx)
  }
}

additionalResolvers

You can provide additional resolvers to the supergraph. This can be useful if you want to add a custom resolver to the supergraph, or override the existing one.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  additionalResolvers: {
    Query: {
      hello: () => 'Hello World'
    }
  }
})

transports (Advanced usage only)

💡

This is an advanced feature and should be used with caution. Use this only if you know what you are doing.

Gateway Transports are the key component of the gateway runtime’s execution. It allows the gateway to communicate with the subgraph. For example @graphql-mesh/transport-rest is used to communicate with the REST subgraphs generated by OpenAPI and JSON Schema source handlers. And GraphQL subgraphs use GraphQL HTTP Transport(@graphql-mesh/transport-http).

Gateway looks up the supergraph, and checks the kind of the subgraph, and loads it by checking the @graphql-mesh/transport-{kind} package, then loads it to create an executor for the subgraph. You can see how an example @transport definition looks like here.

And see the implementation of the default transport loading logic here.

You can replace this logic by providing your own transports.

transportEntries

Most Gateway Transports can be configured using the transportEntries option.

This option is mostly used to customize the subscription transport to be used when it’s not using the one used for queries and mutations. To learn more about subscriptions between gateway and upstream, please visit the Subscriptions page

Otherwise, all configuration is derived from subgraphs definition.

Subgraph matcher

Each subgraph’s transport can be configured by adding a configuration object to the transportEntries map, using the subgraph’s name as a key.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  transportEntries: {
    subgraphName: {
      // configuration for the 'subgraphName' subgraph transport.
    }
  }
})

Most of the time, all subgraph using the same transport will have the same configuration. To avoid duplicating the configuration object for each subgraphs, you can use a transport matcher syntax *.transportKind:

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  transportEntries: {
    '*.http': {
      // configuration for all subgraph using the http transport.
    }
  }
})

If you need to define a configuration for all subgraphs at once, you can use the wildcard matcher *:

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  transportEntries: {
    '*': {
      // configuration for all subgraph using the http transport.
    }
  }
})

If a subgraph mathes multiple transport entries, the configurations are merged with priority for the most specific matcher (subgraphName > *.transportKind > *).

kind

The kind of transport to be used. This will be used by the transports loading mechanism to find the proper transport implementation.

location

The location of the subgraph. Can be either a absolute or a relative path. Defaults to the one defined in the subgraphs configuration.

headers

A list of headers entries to add (when applicable) to the upstream request. Values must be strings, and can be dynamic by including string interpolations.

graphql.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  transportEntries: {
    '*.http': {
      headers: [
        ['authorization', '{context.cookie.authorization}'],
        ['correlation-id', '{context.header.correalation-id}']
      ]
    }
  }
})

options

An additional option object specific to the transport kind. You can find the accepted option here in the specific documentation of each transport.

options.subscriptions

A special case of the option fields is subcriptions. It allows to override the transport options (including the kind) only for subscripions. Please see Subscriptions page for more details.

Subgraphs

If you want to serve a single subgraph, you can provide the subgraph configuration as well. You can generate subgraphs by using GraphQL Mesh or any other Federation compliant tool listed here.

subgraph

You can provide GraphQLSchema, DocumentNode which has the AST of the subgraph or string which is the SDL representation of the subgraph

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  subgraph: './subgraph.graphql',
  // or
  subgraph: 'https://example.com/subgraph.graphql',
  // or you can provide a function that returns a promise of the schema
  subgraph: () =>
    fetch('https://example.com/subgraph.graphql', {
      headers: {
        Authorization: 'Bearer token'
      }
    }).then(res => res.text())
})
💡

The rest of the configuration options are the same as the supergraph configuration.

Configure Hive Gateway as a GraphQL Proxy

proxy

HTTP executor options to proxy all incoming requests to another HTTP endpoint.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  proxy: {
    endpoint: 'https://example.com/graphql'
  }
})

By default, Hive Gateway introspects the schema from the endpoint. And if it fails, it skips the validation and schema aware features. But if Hive CDN endpoint and key have been provided in the configuration, Hive Gateway will fetch the schema from the Hive CDN.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  proxy: {
    endpoint: 'https://example.com/graphql'
  },
  schema: {
    type: 'hive',
    // The endpoint of Hive's CDN
    endpoint: '<graphql schema sdl endpoint>',
    // The CDN token provided by Hive Registry
    key: '<cdn access token>'
  }
})

endpoint

The URL of the GraphQL endpoint to proxy requests to.

headers

Additional headers to include when querying the original schema It can be a plain object or a function that returns a plain object.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  proxy: {
    endpoint: 'https://example.com/graphql',
    headers: execReq => ({
      // This will pass the original request headers to the proxied request
      authorization: execReq.context.headers.authorization
    })
  }
})

useGETForQueries

Whether to use the GET HTTP method for queries when querying the original schema. In that case, the query will be sent as a query string parameter named query.

method

The HTTP method to use when querying the original schema. Default is POST.

timeout

The timeout in milliseconds for the request to the original schema. There is no timeout by default.

retry

Retry attempts in case of a failure. Default is 0.

credentials

Request Credentials (default: ‘same-origin’) Learn more

skipValidation

By default, Hive Gateway validates the operations on the gateway against the introspected schema. This is recommended to keep it enabled for security reasons. But it brings a performance overhead. If you want to disable this validation and send the operations directly to the upstream service, you can set this option to true.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  proxy: {
    endpoint: 'https://example.com/graphql'
  },
  skipValidation: true
})

Configure Server

sslCredentials for HTTPS

This is the option to provide SSL Credentials for HTTPS Server. If this is provided, Hive Gateway will be served via HTTPS instead of HTTP.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  sslCredentials: {
    key_file_name: 'path/to/key.pem',
    cert_file_name: 'path/to/cert.pem',
    ca_file_name: 'path/to/ca.pem',
    passphrase: 'passphrase',
    dh_params_file_name: 'path/to/dhparams.pem',
    ssl_ciphers: 'ECDHE-R',
    // This translates to SSL_MODE_RELEASE_BUFFERS
    ssl_prefer_low_memory_usage: false
  }
})

browser

This is the option to open the browser automatically when the server is started.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  /**
   * Path to the browser that will be used by `Hive Gateway` to open a playground window in development mode
   * This feature can be disabled by passing `false`
   */
  browser: true // or `google-chrome` or `firefox` or `safari` or `edge` or `opera` or `vivaldi` or `brave` or `chromium` or `msedge` or `false`
})

port and host

These are the options to configure the port and host of the server in the configuration file rather than passing them as CLI arguments.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  port: 4000,
  host: 'localhost'
})

maxHeaderSize

This is the option to configure the maximum header size of the server. By default, it is 16KB. If longer headers are sent, the server will respond with a 431 status code.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  maxHeaderSize: 32 * 1024 // 32KB
})

plugins

This is the option to extend your Hive Gateway with plugins. Hive Gateway uses GraphQL Yoga, and Envelop plugin system which allows you to hook into the different phases of the GraphQL execution to manipulate or track the entire workflow step-by-step.

See dedicated plugins feature page for more information

cors

See dedicated CORS feature page for more information

graphiql

You can configure GraphiQL playground that allows you to play with your GraphQL API.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  graphiql: {
    defaultQuery: 'query { hello }'
  }
})

Learn more about available GraphiQL Options from the dedicated GraphQL Yoga page

TODO: Move those into a dedicated GraphiQL page under Features

landingPage

If you want to disable the landing page, you can set this option to false.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  landingPage: false
})

batching

See dedicated page

fetchAPI (Advanced usage only)

💡

This is an advanced feature and should be used with caution. Use this only if you know what you are doing. Use it on your own risk.

Hive Gateway heavily relies on WHATWG Fetch API not only as a HTTP Client but also for handling HTTP Server components. So it uses @whatwg-node/fetch by default which is a platform agnostic implementation of the Fetch API. If you want to use a different Fetch API implementation, you can provide it here.

gateway.config.ts
import fetch from 'node-fetch'
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  fetchAPI: {
    fetch
  }
})

logging

By default, Hive Gateway uses a simple logger that logs to the console by using standard console methods.

Using this option, you can do;

  • Disable logging by providing false
  • Provide your own logger instance
  • Choose a log level
gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
import { createLogger } from 'some-logger-library'
 
export const gatewayConfig = defineConfig({
  logging: createLogger()
  // or
  logging: 'info' // or 'debug' or 'warn' or 'error'
  // or
  logging: false
})

Hive Gateway uses the same logging mechanism of GraphQL Yoga

graphqlEndpoint

This is the option to provide a custom GraphQL endpoint for the server. By default, it is /graphql.

gateway.config.ts
import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  graphqlEndpoint: '/my-graphql-endpoint'
})

maskedErrors

This is enabled by default for security reasons.

Learn more about Error Masking

cache

Provide a cache storage for the server. By default, Hive Gateway uses an in-memory cache.

Learn more about Caching

pubsub

Provide a PubSub instance for the server. By default, Hive Gateway uses an in-memory PubSub. In order to have a better scalability, you can provide a custom PubSub.

Learn more about Subscriptions and Webhooks to see if you need this option

healthCheckEndpoint and readinessCheckEndpoint

Learn more about Health Check and Readiness Check

disableWebsockets

By default Hive Gateway starts a WebSocket server, using the same path than the normal HTTP endpoint. This allows your gateway to be compatible with Subscriptions over WebSockets for incoming client subscriptions out of the box.

This option allows you to disable this WebSockets server.

Hive CLIHive Gateway CLI