Hive Gateway Configuration Reference

An overview of all the configuration options for the gateway.config.ts used by the hive-gateway CLI.

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

Default 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

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.

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())
})

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. So by enabling this option, Hive Gateway can poll the source and update the schema automatically.

If a function is provided as in the example above, that function will be called every time the polling interval is reached.

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

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.

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

transports (Advanced usage only)

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.

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

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())
})

Configure Hive Gateway as a GraphQL Proxy

proxy

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

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

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  proxy: {
    endpoint: 'https://example.com/graphql'
  },
  schema: {
    type: 'hive',
    endpoint: 'https://cdn.graphql-hive.com/artifacts/v1/0123-3434/sdl',
    key: 'SOME_HIVE_KEY'
  }
})

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.

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.

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.

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.

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.

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.

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.

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.

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

batching

See dedicated page

fetchAPI (Advanced usage only)

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.

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

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.

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