---
description: Hive Gateway Configuration Reference
---

import { Callout } from '@theguild/components'

# Hive Gateway Configuration Reference

An overview of all the configuration options for the Hive Gateway, both CLI and
[Progammatic Usage](/docs/gateway/deployment#programmatic-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.

```ts filename="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())
})
```

<Callout type="info">

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

- If you use Hive Registry, please refer to the dedicated section for
  [Fetching Supergraph from Hive Registry CDN](/docs/gateway/supergraph-proxy-source)
- If you use Apollo GraphOS, please refer to the dedicated section for
  [Fetching Supergraph from Apollo GraphOS](/docs/gateway/supergraph-proxy-source).

</Callout>

### 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.

```ts filename="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](/docs/gateway/deployment/serverless) and
having [provided a cache storage](/docs/gateway/other-features/performance#providing-cache-storage),
the remote schema will be stored in the provided cache and the `pollingInterval` option is used as a
TTL.

```ts filename="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.

```ts filename="gateway.config.ts"
import { defineConfig } from '@graphql-hive/gateway'

export const gatewayConfig = defineConfig({
  additionalResolvers: {
    Query: {
      hello: () => 'Hello World'
    }
  }
})
```

### `transports` (Advanced usage only)

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

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](https://the-guild.dev/graphql/mesh/v1/source-handlers/openapi) and
[JSON Schema](https://the-guild.dev/graphql/mesh/v1/source-handlers/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](https://github.com/ardatan/graphql-mesh/blob/master/e2e/auto-type-merging/__snapshots__/auto-type-merging.test.ts.snap#L4).

And see the implementation of the default `transport` loading logic
[here](https://github.com/ardatan/graphql-mesh/blob/master/packages/fusion/runtime/src/utils.ts#L32).

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](/docs/gateway/subscriptions)

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.

```ts filename="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`:

```ts filename="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
`*`:

```ts filename="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.

```ts filename="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](/docs/gateway/subscriptions) 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](https://graphql-mesh.com/) or any other Federation
compliant tool listed
[here](https://www.apollographql.com/docs/federation/building-supergraphs/supported-subgraphs/).

### `subgraph`

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

```ts filename="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())
})
```

<Callout>
  The rest of the configuration options are the same as the supergraph configuration.
</Callout>

## Configure Hive Gateway as a GraphQL Proxy

### `proxy`

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

```ts filename="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.

```ts filename="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.

```ts filename="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](https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials)

### `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`.

```ts filename="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.

```ts filename="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.

```ts filename="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.

```ts filename="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.

```ts filename="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](https://the-guild.dev/graphql/yoga-server/docs/features/envelop-plugins), and
[Envelop](https://the-guild.dev/graphql/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](/docs/gateway/other-features/custom-plugins)

### `cors`

[See dedicated CORS feature page for more information](/docs/gateway/other-features/security/cors)

### `graphiql`

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

```ts filename="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](https://the-guild.dev/graphql/yoga-server/docs/features/graphiql)

`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`.

```ts filename="gateway.config.ts"
import { defineConfig } from '@graphql-hive/gateway'

export const gatewayConfig = defineConfig({
  landingPage: false
})
```

### `batching`

[See dedicated page](/docs/gateway/other-features/performance/request-batching)

### `fetchAPI` (Advanced usage only)

<Callout>
  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.
</Callout>

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`](https://github.com/ardatan/whatwg-node) 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.

```ts filename="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

```ts filename="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](https://the-guild.dev/graphql/yoga-server/docs/features/logging-and-debugging)

### `graphqlEndpoint`

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

```ts filename="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](/docs/gateway/other-features/security/error-masking)

### `cache`

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

[Learn more about Caching](/docs/gateway/other-features/performance)

### `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](/docs/gateway/subscriptions#subscriptions-using-http-callback)

### `healthCheckEndpoint` and `readinessCheckEndpoint`

[Learn more about Health Check and Readiness Check](/docs/gateway/monitoring-tracing#healthcheck)

### `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.
