Environment variables
The 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.
These environment variables can be defined in two different ways:
- on your server (See How To Read and Set Environmental and Shell Variables on a Linux VPS)
- in the
.env
file in your root folder
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 newfront-commerce build
- ✅ if the variable is only used on the server side (
FRONT_COMMERCE_*
but notFRONT_COMMERCE_WEB_*
) you only need to restart your server
- 🚫 if the variable is used on the client side (
- 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
- 🚫 You need to do a new
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.
Front-Commerce related variables
Host
Configure the execution environment of the Front-Commerce’s application:
FRONT_COMMERCE_PORT
(default:4000
): The port of the launched serverFRONT_COMMERCE_HOST
(default:0.0.0.0
): The host of the launched server. It might be useful to set it to127.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
orproduction
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 inFRONT_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 clientFRONT_COMMERCE_UNSAFE_INSECURE_MODE
: you set this environment variable totrue
to disable Front-Commerce behaviors restricting HTTP usage in production, even though we strongly recommend you to expose your application through HTTPS.
In production, Front-Commerce will use thesecure
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 theFRONT_COMMERCE_UNSAFE_INSECURE_MODE
documented above sparingly.
Cache
FRONT_COMMERCE_CACHE_API_TOKEN
: a token that will let external applications invalidate parts of Front-Commerce cache. See Invalidating the cache for more details.
Performance
Removed in version 2.7. Please use Cache-Control headers to improve performance of SSR pages.FRONT_COMMERCE_FAST
: by setting it totrue
, there will be only one render to fetch data server side. cf. Faster Server Side Rendering for more details.ENGINE_API_KEY
: set it to enable Metrics & Logging on your GraphQL schema, using Apollo EngineFRONT_COMMERCE_EXPRESS_COMPRESSION_ENABLED
: set it tofalse
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 thex-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 setFRONT_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 totrue
to turn on an experimental logging of GraphQL resolvers metrics in New Relic. It uses the New Relic Apollo Server pluginFRONT_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 setFRONT_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!
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 MagentoFRONT_COMMERCE_MAGENTO_ENDPOINT
: the URL of the magento (ex: http://magento2.local)WARNING: 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’sfc_cache_api_token
custom variable to enable cache invalidation from Magento2 (configured in « System > Other Settings > Custom Variables » )
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 thedatasource-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 in2.0.0-rc.0
and removed in2.0.0
Algolia
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 AlgoliaFRONT_COMMERCE_ALGOLIA_SEARCH_ONLY_API_KEY
: the search only API keyFRONT_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.
Paypal
More documentation about this module will be available soon. Please contact us directly if you need this information quickly.
FRONT_COMMERCE_WEB_PAYPAL_ENV
:production
orsandbox
- Paypal credentials (See How do I request API Signature or Certificate credentials for my PayPal account?)
FRONT_COMMERCE_PAYPAL_USERNAME
FRONT_COMMERCE_PAYPAL_PASSWORD
Ogone
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_UR
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
: uselyra_collect
to use Lyra Collect instead of PayZen. Default:payzen
.
BuyBox
See our dedicated documentation page.
Capency
See our related documentation for details.
FRONT_COMMERCE_CAPENCY_DISABLED
: set totrue
to temporary disable all the Capency integrationFRONT_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
Build related variables
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 sideWEBPACK
:true
if the javascript code you are executing is bundled with webpack orfalse
if it is server code not within your webpack environmentFRONT_COMMERCE_ENABLE_SOURCE_MAP
:true
if your code needs to expose source maps in production. By default it’sfalse
unless you’ve setFRONT_COMMERCE_ENV=dev
.
Current experiments
FRONT_COMMERCE_EXPERIMENTAL_NEW_RELIC_INSTRUMENT_GRAPHQL_SERVER
: enable Apollo Server experimental NewRelic instrumentationFRONT_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 actionsfront-commerce:algolia
: debugs detailed information about Algolia queries and interactionsfront-commerce:authorization
: debugs proxy authorization for remote sources (seemakeProtectedProxyRouter.js
)front-commerce:cache
: debugs cache invalidation calls and strategies informationfront-commerce:cart
: debugs cart corrupted data received from remote sourcesfront-commerce:cluster
: debugs the node process id and other information to help configuring cluster modefront-commerce:config
: dumps the configuration for a typical request at the/__front-commerce/debug
URLfront-commerce:dispatcher
: debugs information about routes dispatching for registered page typesfront-commerce:elasticsearch
: debugs all elasticsearch queries (VERY VERBOSE!)front-commerce:graphql
: debugs GraphQL related codefront-commerce:httpauth
: debugs how basic authorization is enabledfront-commerce:image
: debugs image proxy actions (useful to troubleshoot interactions with remote media servers)front-commerce:payment
: debugs payment interactions to help troubleshooting a payment workflowfront-commerce:payment:adyen
: debugs advanced Adyen information (several information are also logged inserver.log
no matter this flag)front-commerce:payment:buybox
: debugs HTTP interactions with BuyBox API (several information are also logged inserver.log
no matter this flag)front-commerce:performance
: allow to debug server performance in production by enabling server timingsfront-commerce:prismic
: turns the Prismic module debug onfront-commerce:prismic:cache
: debugs the Prismic caching layer specifically. Can be targetted directly, or included with the previous namespace usingDEBUG=front-commerce:prismic*
front-commerce:scripts
: debugs all scripts and tooling related commands (webpack…)front-commerce:scripts:routes
: debugs routing generation during theprepare
commandfront-commerce:shipping:mondialrelay
: debugs MondialRelay related operationsfront-commerce:smart-forms:capency
: debugs full requests, responses and errors related to Capency’s webservicefront-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 internalsfront-commerce:webpack
: enableswebpack-bundle-analyzer
on webpack client’s bundlefront-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.
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_
, includingFRONT_COMMERCE_WEB_