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())
})
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
- If you use Apollo GraphOS, please refer to the dedicated section for Fetching Supergraph from Apollo GraphOS.
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)
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.
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
:
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
*
:
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.
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
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.
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.
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
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.
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.
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