Configure brX GraphQL Service

This Bloomreach Experience Manager feature requires a standard or premium license. Please contact Bloomreach for more information.


The brX GraphQL Service reads the environment configuration from .env file to integrate with the Commerce Backend Platform. The .env file contains the connection information to the Commerce Backend Platform and other configuration options.

Environment Configuration File

The brX GraphQL Service requires the environment configuration file named .env in the project root folder. An example file is provided as .env.dist in the project root folder, so you can copy the file to .env first and edit the content with correct information.

The .env file consists of the three groups of configuration options:

  1. General Options: the options which are generally applied to the brX GraphQL Service, regardless of the specific Commerce Backend Platform.
  2. Bloomreach Discovery Connection Settings: the connection settings to integrate with Bloomreach Discovery.
  3. Commerce Backend Platform Connection Settings: the connection settings to integrate with the specific Commerce Backend Platform(s).

An example .env file looks like the following (lines starting with '#' are comments):

# 1. General Options


# 2. brSM Connection Settings


# 3. Commerce Backend Platform Connection Settings (commercetools in this example)


# ... More Commerce Backend Platform Connection Options may follow ...

General Options

The following options are supported:

Property Name Description Default Value
NODE_ENV This is an environment variable used by Express and Apollo Server internally, on which brX GraphQL Service is implemented.
For example, if this is set to 'development', then the internal RESTDataSource implementation of the Apollo Server prints out a log to STDOUT whenever making an HTTP request against the external URL.
Also, if this is set to 'production', then any development specific features such as Apollo Server GraphQL Playground won't be available.
PORT The server port of the brX GraphQL Service. 4000
LOG_LEVEL The log level specifying the minimum level of logging to be transported to the log output. brX GraphQL Service uses Winston library for logging. See the available log levels of the library for detail. 'info'
DEBUG_TRACE_PAYLOAD If set to 'true', the built-in DataSource implementations of the brX GraphQL Service prints out the responses from the external endpoint of the Commerce Backend Platform to STDOUT for debugging purpose. Note that it is not recommended to set this to 'true' in production. 'false'
APOLLO_INTROSPECTION If set to 'true', the Apollo Server Introspection technique is enabled to provide detailed information about a GraphQL API's schema. 'false'
APOLLO_PLAYGROUND If set to 'true', the Apollo Server GraphQL Playground, the in-browser IDE for GraphQL development and workflow, is enabled to provide developers with features such as theme change, automatic schema reloading, HTTP headers configuration, query history and GraphQL subscription support. 'false'
JWK_KEYSTORE The keystore configuration for the brX GraphQL Service generates a secure, encrypted access token for visitors. See Access Management in brX GraphQL Service for detail.  

The allowed origin which wants to access the brX GraphQL Service as a Cross-Origin Resource Sharing target.
If this is not set or set to an empty string, then the brX GraphQL Service allows access to the clients sending a valid 'Origin' request header.
If set to '*', then the brX GraphQL Service allows access to any clients.
If set to a specific URL (e.g,, then the brX GraphQL Service allows access only to the clients which are originated from the URL.


If set to 'true', the Refreshing Access Token request against Access Management is enabled on the brX GraphQL Service. This option has been disabled by default since v14.3.0.

DEFAULT_CONNECTOR_ID brX GraphQL Services reads the Commerce Connector ID from the HTTP request header named 'connector'. If the GraphQL client does not provide a valid Commerce Connector ID value, then this variable is used instead. 'brsm'


The default language code for the client. 'en'
DEFAULT_COUNTRY The default country code for the client. 'US'
DEFAULT_CURRENCY The default currency code for the client. 'USD'
RESPONSE_TIME_HEADER_ENABLED If set to 'true', the internal response time in milliseconds measured in the brX GraphQL Service is passed in the X-Response-Time response header.  

Bloomreach Discovery and Commerce Backend Platform Connection Settings and Connector IDs

Bloomreach Discovery and the following Commerce Backend Platforms are supported (differentiated by each unique 'connector' identifier in request header):

Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?