Skip to main content
Version: 2.x

Environment variables

Environment variables available in Front-Commerce are the configurations that are likely to change depending on the current environment of your application. For instance, you could have three different environments: production, staging, and local.

Environment variables documented in this guide can be defined in two different ways:

You can then access them by using the process.env object in your javascript files no matter if it is a server-side or client-side file. However, not all variables are exposed in your client code. Client code only have access to variables such as FRONT_COMMERCE_WEB_* which were defined during front-commerce build. See Add your own environment variables for more details.

How to update environment variables​

You can't update these variables only by updating your server's variable. This comes from how node works. But there are also some specificities due to Front-Commerce.

  • If FRONT_COMMERCE_USE_SERVER_DYNAMIC_ENV=true during build time:
    • 🚫 if the variable is used on the client side (FRONT_COMMERCE_WEB_*) you need to do a new front-commerce build
    • ✅ if the variable is only used on the server side (FRONT_COMMERCE_* but not FRONT_COMMERCE_WEB_*) you only need to restart your server
  • If FRONT_COMMERCE_USE_SERVER_DYNAMIC_ENV=false during build time (default behavior until 1.0.0):
    • 🚫 You need to do a new front-commerce build and restart your server

The reason behind these rules is because some variables are defined and bundled within your code during the build of your application. For this reason, if you are are in a case where you can't update the variable, you will need to trigger a new build with the new environment variables defined and restart your server.

Host​

Configure the execution environment of the Front-Commerce's application:

  • FRONT_COMMERCE_PORT (default: 4000): The port of the launched server
  • FRONT_COMMERCE_HOST (default: 0.0.0.0): The host of the launched server. It might be useful to set it to 127.0.0.1 if you want to only listen local requests.
  • FRONT_COMMERCE_URL: The URL available to access to your Front-Commerce application (http://localhost:4000 in your local environment, and your website URL on the production environment)
  • FRONT_COMMERCE_ENV: dev or production in order to remove debugging options on the server side (ex: we disable GraphQL playground in production mode)
  • FRONT_COMMERCE_COOKIE_DOMAIN (deprecated): the domain of your cookie, most likely the same one used in FRONT_COMMERCE_URL (ex: localhost or the your domain name). Deprecation reason: the cookie domain will now be defined automatically by the browser.
  • FRONT_COMMERCE_COOKIE_PASS: a secret to secure the cookies exchanged with the client
  • FRONT_COMMERCE_UNSAFE_INSECURE_MODE: you set this environment variable to true to disable Front-Commerce behaviors restricting HTTP usage in production, even though we strongly recommend you to expose your application through HTTPS.
note

In production, Front-Commerce will use the secure mode for setting cookies to force running the application in HTTPS. If your production instance is not in HTTPS, you will encounter issues when logging in. That is why Front-Commerce redirects user to the HTTPS version of a page in this case. Use the FRONT_COMMERCE_UNSAFE_INSECURE_MODE documented above sparingly.

Cache​

Performance​

  • FRONT_COMMERCE_FAST: by setting it to true, there will be only one render to fetch data server side. cf. Faster Server Side Rendering for more details. Removed in version 2.7. Please use Cache-Control headers to improve performance of SSR pages.
  • ENGINE_API_KEY: set it to enable Metrics & Logging on your GraphQL schema, using Apollo Engine
  • FRONT_COMMERCE_EXPRESS_COMPRESSION_ENABLED: set it to false to disable server responses compression. It allows to reduce your server CPU usage in contexts where a frontend CDN or proxy can handle compression more efficiently. It can also be disable per request, if the request contains the x-no-compression header.

Server​

  • FRONT_COMMERCE_EXPRESS_LOG_ACCESS_ENABLED: in some contexts, the proxy already has access logs and it is not useful to have a duplication. Logs grow unnecessarily and it adds an overhead. You can set FRONT_COMMERCE_EXPRESS_LOG_ACCESS_ENABLED=false to disable Front-Commerce access logs (in logs/access.log).
  • FRONT_COMMERCE_EXPERIMENTAL_NEW_RELIC_INSTRUMENT_GRAPHQL_SERVER: set it to true to turn on an experimental logging of GraphQL resolvers metrics in New Relic. It uses the New Relic Apollo Server plugin
  • FRONT_COMMERCE_GRAPHQL_PERSISTED_QUERIES_DISABLE: in some contexts GraphQL persisted queries can be a blocker for a task. For instance, when recording a stress test scenario you might want fully reproducible HTTP traffic: persisted queries may lead to unreproducible recordings. In this case, you can set FRONT_COMMERCE_GRAPHQL_PERSISTED_QUERIES_DISABLE=true to disable the GraphQL server persisted queries feature (upon restart). Don't forget to turn it on again afterwards: it is recommended for production use cases!
  • FRONT_COMMERCE_COOKIE_MAX_AGE_IN_MS: the duration of the customers' session in milliseconds (default: one day)
  • FRONT_COMMERCE_ENABLE_ROLLING_SESSIONS: If "true", enable express session rolling. This options extends duration of the customers' session cookies (using the value from FRONT_COMMERCE_COOKIE_MAX_AGE_IN_MS) when they interact with the website

Sitemap​

  • FRONT_COMMERCE_SITEMAP_TOKEN: a token that secures the sitemap query in your GraphQL Schema

PWA​

  • FRONT_COMMERCE_DISABLE_OFFLINE_MODE: in case you don't want to load the offline page when the user is offline

DX​

  • FRONT_COMMERCE_DEV_SSR_FALLBACK_DISABLE: disables the SSR warning page before loading. This allows you to see what happens in production.
  • FRONT_COMMERCE_DEV_IMAGE_ERROR_DISABLE: disables the image resizing errors in case you've passed malformed requests to the server. This allows you to see what happens in production.

Remote services configuration​

Your Front-Commerce application is an empty shell if it's not connected to remote services. These following sections document which variables are needed for each one of these.

Magento 2​

  • FRONT_COMMERCE_MAGENTO_MODULE_VERSION: the version of the Front-Commerce module installed on your Magento
  • FRONT_COMMERCE_MAGENTO_ENDPOINT: the URL of the Magento instance (ex: http://magento2.local)
caution

Due to the way token based authentication is implemented in Magento2 Web API, using a URL containing basic authentication credentials (such as http://user:password@magento2.local) is not possible yet. It would prevent users to login.

  • Integration tokens configured in Magento’s System > Extensions > Integrations admin page:
    • FRONT_COMMERCE_MAGENTO_CONSUMER_KEY
    • FRONT_COMMERCE_MAGENTO_CONSUMER_SECRET
    • FRONT_COMMERCE_MAGENTO_ACCESS_TOKEN
    • FRONT_COMMERCE_MAGENTO_ACCESS_TOKEN_SECRET
  • FRONT_COMMERCE_MAGENTO_ADMIN_TOKEN: Admin role token to detect admin users in Front-Commerce configured in « Stores > Configurations > General > General > Front-Commerce > Magento Admin Token »
  • FRONT_COMMERCE_CACHE_API_TOKEN: The key configured here must be identical to Magento’s fc_cache_api_token custom variable to enable cache invalidation from Magento2 (configured in « System > Other Settings > Custom Variables » )
  • FRONT_COMMERCE_MAGENTO_TIMEOUT: The timeout in milliseconds for Magento requests (default: 60000)
  • FRONT_COMMERCE_MAGENTO_ADMIN_TIMEOUT: The timeout in milliseconds for Magento requests that require admin privileges (default: 10000)
  • FRONT_COMMERCE_OPTIMIZED_ADD_MULTIPLE_CART_ITEMS: set it to true to use an alternative implementation of the addMultipleItemsToCart mutation that is more performant when adding a high number of products to the cart.

Magento 1​

  • FRONT_COMMERCE_MAGENTO_MODULE_VERSION: the version of the Front-Commerce module installed on your Magento
  • FRONT_COMMERCE_MAGENTO_ENDPOINT: the URL of the Magento instance (ex: http://magento1.local)
  • Integration tokens configured in Magento’s Front-Commerce > Configuration
    • FRONT_COMMERCE_MAGENTO_CONSUMER_KEY
    • FRONT_COMMERCE_MAGENTO_CONSUMER_SECRET
    • FRONT_COMMERCE_MAGENTO_ACCESS_TOKEN
    • FRONT_COMMERCE_MAGENTO_ACCESS_TOKEN_SECRET
  • FRONT_COMMERCE_CACHE_API_TOKEN: The key configured here must be identical to the Cache token setting available in the admin interface under Front-Commerce > Configuration > Cache Settings
  • FRONT_COMMERCE_XRAY_MAGENTO_VERSION: The magento 1 version you are using (default: openmage, possible values: openmage, magento1)
  • FRONT_COMMERCE_MAGENTO_TIMEOUT: The timeout in milliseconds for Magento requests (default: 60000)
  • FRONT_COMMERCE_MAGENTO_ADMIN_TIMEOUT: The timeout in milliseconds for Magento requests that require admin privileges (default: 10000)

BigCommerce​

  • Access to the Management API: follow the Creating an API Account guide and then with the generated text file fill the following variables:
    • FRONT_COMMERCE_BIG_COMMERCE_ENDPOINT contains the API PATH without the /v3/ suffix e.g. something like https://api.bigcommerce.com/stores/<storeHash>
    • FRONT_COMMERCE_BIG_COMMERCE_AUTH_TOKEN contains the ACCESS TOKEN
    • FRONT_COMMERCE_BIG_COMMERCE_CLIENT_ID contains the CLIENT ID
    • FRONT_COMMERCE_BIG_COMMERCE_CLIENT_SECRET contains the CLIENT SECRET
    • FRONT_COMMERCE_BIG_COMMERCE_STORE_HASH contains the store hash, it's the last part of the FRONT_COMMERCE_BIG_COMMERCE_AUTH_TOKEN described above.
  • Reset password:
    • FRONT_COMMERCE_BIG_COMMERCE_RESET_PASSWORD_SMTP_CONNECTION_STRING contains the SMTP connection string used to send password reset emails e.g. something like smtps://login:mypassword@smtp.example.com:465. Both smtp and smtps are supported; login, password and port are optional.
    • FRONT_COMMERCE_BIG_COMMERCE_RESET_PASSWORD_SENDER_EMAIL_ADDRESS contains a plain email address (noreply@example.com) or a formatted sender (My store <noreply@example.com>) used as the sender of reset password emails.
  • FRONT_COMMERCE_BIG_COMMERCE_WEBHOOK_SECRET contains the webhook secret, see Configure the webhook secret

Elasticsearch​

When your products are indexed in an Elasticsearch, you should put these variables:

  • FRONT_COMMERCE_ES_HOST: the host of your Elasticsearch instance, without trailing slash (ex: http://es.front-commerce.local:9200)
  • FRONT_COMMERCE_ES_ALIAS: the alias prefix shared for your stores Elasticsearch indexes (ex: magento2). The store code will be appended.
  • FRONT_COMMERCE_ES_DISABLE: setting it to "true" allows to disable the use of Elasticsearch. As of 2.5.0, if you don't want to use Elasticsearch at all, you can simply not enable the datasource-elasticsearch module. This environment can still be used to quickly disable Elasticsearch usage without changing the code.
  • FRONT_COMMERCE_ES_ELASTICSUITE_VERSION: the version of the ElasticSuite module installed (only relevant for Magento2 based setup). By default, Front-Commerce considers a version < 2.9.
  • FRONT_COMMERCE_ES_VERSION: Elasticsearch server version (ex: 6.7) deprecated in 2.0.0-rc.0 and removed in 2.0.0

Algolia​

info

As of Front-Commerce 2.6, the Algolia Front-Commerce module is automatically configured based on Magento1 configuration. Those environment variables only apply to Front-Commerce 2.5 with Magento1.

  • FRONT_COMMERCE_ALGOLIA_APPLICATION_ID: the Application ID that identify your application in Algolia
  • FRONT_COMMERCE_ALGOLIA_SEARCH_ONLY_API_KEY: the search only API key
  • FRONT_COMMERCE_ALGOLIA_INDEX_NAME_PREFIX: a prefix to use to build index names

You can find these credentials on the Algolia Dashboard, on the API keys page from the menu.

Attraqt​

  • FRONT_COMMERCE_ATTRAQT_SEARCH_API_KEY: your attraqt search api key, found in the XO console under Search > API Keys
  • FRONT_COMMERCE_ATTRAQT_RECOMMENDATION_API_URL: Attraqt's recommendation API url
  • FRONT_COMMERCE_ATTRAQT_DISABLED (since 2.23): setting it to true disables Attraqt search temporarily. This environment can be used to quickly disable Attraqt search without changing the code. To remove the module definitely, remove it from .front-commerce.js instead.

Paypal​

WIP

More documentation about this module will be available soon. Please contact us directly if you need this information quickly.

Ogone​

WIP

More documentation about this module will be available soon. Please contact us directly if you need this information quickly.

  • FRONT_COMMERCE_OGONE_ENV
  • FRONT_COMMERCE_OGONE_PSPID
  • FRONT_COMMERCE_OGONE_SECRET
  • FRONT_COMMERCE_OGONE_ALGO
  • FRONT_COMMERCE_OGONE_USERNAME
  • FRONT_COMMERCE_OGONE_PASSWORD
  • FRONT_COMMERCE_OGONE_ACCEPT_URL
  • FRONT_COMMERCE_OGONE_EXCEPTION_URL
  • FRONT_COMMERCE_OGONE_TIMEOUT: timeout in milliseconds for the Ogone requests. (default: 10000)

Payzen​

Get your access keys by following the Payzen documentation. See our documentation page for further details.

  • FRONT_COMMERCE_PAYZEN_PUBLIC_KEY
  • FRONT_COMMERCE_PAYZEN_PRIVATE_KEY
  • FRONT_COMMERCE_PAYZEN_SHA256
  • FRONT_COMMERCE_PAYZEN_PRODUCT: use lyra_collect to use Lyra Collect instead of PayZen. Default: payzen.

BuyBox​

See our dedicated documentation page.

Stripe​

  • FRONT_COMMERCE_STRIPE_SECRET_KEY
  • FRONT_COMMERCE_WEB_STRIPE_PUBLISHABLE_KEY
  • FRONT_COMMERCE_STRIPE_DISABLE_CAPTURE
  • FRONT_COMMERCE_STRIPE_MAX_NETWORK_RETRY

See Stripe documentation page for details.

Capency​

See our related documentation for details.

  • FRONT_COMMERCE_CAPENCY_DISABLED: set to true to temporary disable all the Capency integration
  • FRONT_COMMERCE_CAPENCY_AUTH_USERNAME
  • FRONT_COMMERCE_CAPENCY_AUTH_PASSWORD
  • FRONT_COMMERCE_CAPENCY_URL_CAP_EMAIL
  • FRONT_COMMERCE_CAPENCY_URL_CAP_ADDRESS
  • FRONT_COMMERCE_CAPENCY_URL_CAP_PHONE

Prismic​

See our related documentation for details.

  • FRONT_COMMERCE_PRISMIC_REPOSITORY_NAME
  • FRONT_COMMERCE_PRISMIC_ACCESS_TOKEN
  • FRONT_COMMERCE_PRISMIC_WEBHOOK_SECRET
  • #FRONT_COMMERCE_PRISMIC_API_CACHE_TTL_IN_SECONDS

Wordpress​

Colissimo​

See our related documentation for details.

Contribution mode​

  • FRONT_COMMERCE_CONTRIBUTION_MODE_FORCE: force the contribution mode by setting it to true.

  • FRONT_COMMERCE_COLISSIMO_TIMEOUT: timeout in milliseconds for the Colissimo requests. (default: 60000)

  • NODE_ENV: "development" or "production" a variable heavily used in the javascript ecosystem to let you add checks only on the development environment (warnings, guards, etc.)
  • SERVER: true if your code is executed server side, false if it is client side
  • WEBPACK: true if the javascript code you are executing is bundled with webpack or false if it is server code not within your webpack environment
  • FRONT_COMMERCE_ENABLE_SOURCE_MAP: true if your code needs to expose source maps in production. By default it's false unless you've set FRONT_COMMERCE_ENV=dev.

Current experiments​

  • FRONT_COMMERCE_EXPERIMENTAL_NEW_RELIC_INSTRUMENT_GRAPHQL_SERVER: enable Apollo Server experimental NewRelic instrumentation
  • FRONT_COMMERCE_EXPRESS_SHOP_FALLBACK_REDIRECT_HTTP_CODE: allow to change the default store fallback HTTP code

Debugging​

Since version 1.0.0-beta.0

Front-Commerce leverages the debug package to show useful debugging information in the console. The DEBUG environment variable can be used to enable logging for different part of Front-Commerce, and some of the used libraries.

Front-Commerce debugs are in the front-commerce namespace. One can enable all of them using the following definition: DEBUG="front-commerce:*"

The core also allows you to debug API calls to remote services made in the server. To do so, define DEBUG=axios.

Both examples above can be combined as follow: DEBUG="front-commerce:*,axios". Learn more in the debug package documentation.

Here is a list of available debug namespaces:

  • axios: debugs axios requests and responses (using axios-debug-log)
  • express-http-proxy: debugs media requests proxied by the media middleware (see express-http-proxy)
  • express-session: debugs cookies and how sessions are stored for each request (see express-session)
  • front-commerce:admin-bar: debugs calls and role injection mechanisms for logging as a customer and other actions
  • front-commerce:algolia: debugs detailed information about Algolia queries and interactions
  • front-commerce:attraqt: debugs detailed information about Attraqt queries and interactions
  • front-commerce:authorization: debugs proxy authorization for remote sources (see makeProtectedProxyRouter.js)
  • front-commerce:b2b:companyCredit: debugs B2B company credit interactions
  • front-commerce:b2b:permissions: debugs B2B permissions interactions
  • front-commerce:big-commerce:*: debugs Big Commerce module queries and interactions, here a list of all Big Commerce related debug flags:
    • front-commerce:big-commerce:address
    • front-commerce:big-commerce:cache
    • front-commerce:big-commerce:cart
    • front-commerce:big-commerce:category
    • front-commerce:big-commerce:checkout
    • front-commerce:big-commerce:core
    • front-commerce:big-commerce:customer
    • front-commerce:big-commerce:hacks
    • front-commerce:big-commerce:layer
    • front-commerce:big-commerce:navigation
    • front-commerce:big-commerce:order
    • front-commerce:big-commerce:product
    • front-commerce:big-commerce:reset-password
    • front-commerce:big-commerce:url
    • front-commerce:big-commerce:wishlist
  • front-commerce:cache: debugs cache invalidation calls, strategies information and HTTP Cache deactivation.
  • front-commerce:cart: debugs cart corrupted data received from remote sources
  • front-commerce:cart:cache: debugs cache information for customer's cart (see Caching customers' cart)
  • front-commerce:customer:cache: debugs cache information for current user's information (see Caching current customers' information for Magento2)
  • front-commerce:cluster: debugs the node process id and other information to help configuring cluster mode
  • front-commerce:config: dumps the configuration for a typical request at the /__front-commerce/debug URL
  • front-commerce:country: debugs Big Commerce country related API calls
  • front-commerce:customer: debugs Big Commerce customer related API calls
  • front-commerce:customer:cache: debugs customer cache related operations
  • front-commerce:dispatcher: debugs information about routes dispatching for registered page types
  • front-commerce:elasticsearch: debugs all elasticsearch queries (VERY VERBOSE!)
  • front-commerce:graphql: debugs GraphQL related code
  • front-commerce:hipay: debugs HiPay module queries and interaction
  • front-commerce:httpauth: debugs how basic authorization is enabled
  • front-commerce:image: debugs image proxy actions (useful to troubleshoot interactions with remote media servers)
  • front-commerce:in-stock-alert: debugs In Stock Alert API calls
  • front-commerce:magento2:search: debugs Magento2 native search queries and interaction
  • front-commerce:payment: debugs payment interactions to help troubleshooting a payment workflow
  • front-commerce:payment:adyen: debugs advanced Adyen information (several information are also logged in server.log no matter this flag)
  • front-commerce:payment:buybox: debugs HTTP interactions with BuyBox API (several information are also logged in server.log no matter this flag)
  • front-commerce:performance: allow to debug server performance in production by enabling server timings
  • front-commerce:prismic: turns the Prismic module debug on
  • front-commerce:prismic:*: debugs various aspects of the Prismic module, here is the available list of Prismic related flags:
    • front-commerce:prismic:cache
    • front-commerce:prismic:fetch
    • front-commerce:prismic:webhook
  • front-commerce:remote-schemas: debugs remote schema related code
  • front-commerce:rma: debugs Return Merchandize Authorization related queries and interactions
  • front-commerce:scripts: debugs all scripts and tooling related commands (webpack…)
  • front-commerce:scripts:routes: debugs routing generation during the prepare command
  • front-commerce:shipping:chronorelais: debugs ChronoRelais related operations
  • front-commerce:shipping:mondialrelay: debugs MondialRelay related operations
  • front-commerce:smart-forms:capency: debugs full requests, responses and errors related to Capency's webservice
  • front-commerce:store-credits: debugs responses and errors related to store credit (Magento 1 EE / Magento 2 Commerce)
  • front-commerce:remote-schemas: debugs remote schema stitching related internals
  • front-commerce:webpack: enables webpack-bundle-analyzer on webpack client's bundle
  • front-commerce:in-stock-alert: debugs responses and errors related to in-stock alerts

Note: one can run the rg -iF '"front-commerce:' to find these values.

note

In development environment, the source maps for both the server and the client side are generated. That means you can follow our Debugging Guide to get started with JavaScript Debugging.

Deprecation warnings​

Front-Commerce leverages the depd package to show deprecation warnings so you can upgrade your codebase for compatibility with the next major version.

A meaningful module name is used to scope depd messages, and appears at the beginning of every output line.

One can leverage depd's TRACE_DEPRECATION environment variable to display a stack trace for each deprecation. It will help you to find the line of code in your codebase that calls deprecated code.

Example:

TRACE_DEPRECATION=*

Add your own environment variables​

Depending on the amount of customization you add to your Front-Commerce application, you may need to add new environment variables. This is possible and don't need any particular steps. However, please keep in mind that the ones that are safely available in your bundles are:

  • in your client bundle: all the variables starting with FRONT_COMMERCE_WEB_
  • in your server bundle: all the variables starting with FRONT_COMMERCE_, including FRONT_COMMERCE_WEB_