Skip to main content
Version: 2.x

Configurations

This reference documentation is about existing Front-Commerce configuration files.

note

Most configurations in Front-Commerce are now using Environment variables and Configuration providers. We invite you to also read these related pages.

How to set your configurations​

Each file described below exist in node_modules/front-commerce/src/config in Front-Commerce. If you want to override some, duplicate those in my-module/config.

New in version 1.0.0-beta.3: configurations are inherited across themes declared in your .front-commerce.js in a similar fashion than theme overrides.

Security Notice

Please keep in mind that most of these configurations are imported and bundled into your client application. Thus it is important to not include private configurations in them, and to use environment variables instead.

config/website.js​

search.attributeFacetMinimumDocumentCount and search.categoryFacetMinimumDocumentCount have been added in Front-Commerce 2.3.0. Before this version, Front-Commerce behaved as if those parameters were set to 1.

This configuration file should contain any thing that impacts the content of your website. The term website refers to what a website is in Magento's ecosystem.

  • root_categories_path (ex: 1/517/): which category to use for the main navigation menu. Removed in 2.7.0.
  • cookieMaxAgeInMonths the consent cookie's maxage in months. The consent cookie stores the user cookies authorizations and when cleared the cookie banner will reapear to the user on next visit. As of 2.12.0 and patch releases 2.11.1, 2.10.3, 2.9.5, 2.8.6, 2.7.4, 2.6.3, 2.5.5, 2.5.5, 2.4.9 the default will be 12 month but if you are on Front-Commerce version less than the ones above configuring cookieMaxAgeInMonths in your src/config/website.js IS A MUST. Otherwise you run the risk of the cookie banner showing to your user everytime he closes and opens his browser. Which is very annoying to the user and may lead to the user denying consent and thus the loss of valuable analytics insights.
  • default_image_url (ex: an absolute URL of an image): which image to use when no image path has been given to <ResizedImage>
  • defaultTitle: the default meta title of your application
  • defaultDescription: the default meta description of your application
  • available_page_sizes: which page sizes to display in a product list page (or any page with a pagination)
  • website_id: which website is used within magento (needed for customer related mutations)
  • tax (ex: 1.2 for 20% VAT): Used to correctly filter products within layer queries (this configuration should soon be deprecated with search updates in Front-Commerce — see #102)
  • contentSecurityPolicy: the CSP configuration see the related guide
  • search: an object that defines how the Elasticsearch queries should be made.
    • dynamicFacetSize: number of filters to fetch from Elasticsearch
    • ignoredAttributeKeys: attribute codes to ignore when generating facets with Elasticsearch
    • attributeFacetMinimumDocumentCount: the minimum number of document an attribute facet needs to match to be displayed. It is set to 1 by default, that means only attribute facets leading to at least one document are displayed. By setting it to 0, attribute facets leading to no document are also displayed but disabled in the UI.
    • authorizedCategoriesFacet: array of ids of the categories that should be displayed in the filters. The string "*" can be used to allow all categories. Default value: [].
    • categoryFacetMinimumDocumentCount: the minimum number of document a category facet needs to match to be displayed. It is set to 1 by default, that means only category facets leading to at least one document are displayed. By setting it to 0, category facets leading to no document are also displayed but disabled in the UI.
    • useAttributeLabels: if set to true, the attribute labels will be used instead of the attribute codes in the filters. Default value: false.
  • theme-color: a CSS value that will be used in your layout for a <meta name="theme-color" />
  • phoneNumber: support/contact number of the website
  • email: support/contact email of the website
  • maxAddressLength: max length for one line of address (default is 35)
  • rewrittenToRoot: array of the URLs that should be redirected to /
  • preload: an object that defines how the preload features work in Front-Commerce
    • maxConcurrentPreload: the number of parallel requests that can be launched for preloading purpose (default: 3)
    • maxPreloadQueueLength: the number of preload requests to store before aborting old ones (default: 30)
    • intersectionObserverOptions: IntersectionObserver options to know when to trigger a preload based on a link's position on screen (default: { rootMargin: "0px" })
    • timeoutBeforePreload: the duration in milliseconds to wait before triggering a link's preload once it has entered the screen (default: 500)
    • intersectionObserverDevices: the type of devices where intersection observers should be used for preload. We usually don't want it on desktop to avoid triggering too many requests. (default: ["phone", "tablet"])
  • hasDefaultAddressSupport: a boolean that controls if the customer can set addresses as default for billing and shipping (default: true)

You could find many other configurations in such a file because some configurations could come from optional modules. Some of these are:

  • color_attribute_id: allows to display the colors swatches for the color attribute (swatches should be detected automatically in the future)
  • mapsKey: Google maps key for Colissimo shipping method

config/licences.js​

This makes it possible to configure the GSC text.

This file should export an object where the keys are the store's code (see Configure multiple stores) and the value is a string (with some html content if needed).

config/httpAuth.js​

Configure a Basic Authentication on your server (usually for dev environments).

module.exports = {
  // enable basic authentication
  enable: true,
  // allow these IPs to bypass the basic authentication
  whitelist: [
    "x.x.x.x",
  ]

  // Headers where it's most likely to find the client IP
  // Useful for logging the client's ip in the client logger (cf. https://gitlab.blackswift.cloud/front-commerce/front-commerce/issues/23)
  headers: ["x-real-ip", "x-forwarded-for"],
};

To configure which login/password to use with the Basic Authentication, setup the file .htpasswd at the root of your project.

headers​

The headers configuration in config/httpAuth.js exists to let the server know how to retrieve the client's IP (for logging and debugging purpose). This is because most node servers are behind proxies that pass the client's IP as a HTTP request header.

Thus, if you are indeed behind a proxy, you must make sure that:

  1. The client's IP is passed within a header
  2. the headers array contains the header's key

By default most proxies are setting either x-real-ip or x-forwarded-for. So that's a sane default. But if you have some issues retrieving the client's IP, please check that those headers are correctly configured within your proxy.

note

This setting is used even without enabling basic authentication to pass the client IP to the third party servers.

config/hardcodedSitemap.js​

Allows to define static routes within your application that aren't already fetched dynamically from your backend. Each object should match the Sitemapable interface of src/server/model/store/schema.gql

module.exports = [
  {
    path: "/",
    priority: 1,
    changefreq: "daily",
    lastmod: new Date("2017-06-01").toISOString(),
  },
];

config/autocomplete.js​

Allows to define which kind of entities should be returned within the search bar.

Available values are : "products", "categories" and "pages".

module.exports = ["products", "categories", "pages"];

config/caching.js​

Allows to define configurations related to dataloader caching and implementations. It can export a configuration with the following keys:

  • defaultMaxBatchSize: default batch size used for dataloaders (unless specified during instantiation) (default: 100)
  • strategies: list of caching strategies to use in the application (default: [])

Each strategy can be configured with the keys below:

  • implementation: name of the implementation of this strategy (mandatory)
  • supports: list of loaders impacted by this strategy. Either an array of values or "*" for all. (mandatory)
  • disabledFor: list of loaders not impacted by this strategy (default: [])
  • config: an object containing implementation specific configuration (default: {})
note

Loaders are identified with a key. The key is the first argument passed to the makeDataLoader factory.

Example of a recommended configuration for Magento stores.

Reminder: ensure to take a look at the redis strategy for the fully configured redis setup

export default {
  defaultMaxBatchSize: 100,
  strategies: [
    {
      implementation: "Redis",
      supports: "*",
      config: {
        host: "redis",
        // full configuration at https://developers.front-commerce.com/docs/2.x/advanced/graphql/dataloaders-and-cache-invalidation#redis
      },
    },
    {
      implementation: "PerMagentoCustomerGroup",
      supports: ["CatalogPrice"],
      config: {
        defaultGroupId: 0,
      },
    },
  ],
};

config/sessions.js​

Allows to define configurations related to the sessions of the users connected to your website.

  • store: factory function to use a custom data store to support sessions rather than the default one relying on the filesystem. For instance, if you want to connect to redis, you would have to return in the store function a new RedisStore(options) from connect-redis.

See details and examples in the Setup sessions page.

config/rateLimit.js​

Allows to define configurations related to GraphQL rate limiting feature.

  • store: factory function to use a custom data store to support rate limiting memory

See Use a persistent store for further information.

config/images.js​

Allows to define configurations related to images and image resizing to ensure the best performance.

  • defaultBgColor: background of your images if they are not in the correct ratio
  • presets: different formats available
tip

In addition to the presets explicitly declared, there is also an original preset which allows to retrieve the image without any transformation.

⚠️ this format should be used with caution as these images would be unoptimised, it is expected that you take care of the optimisation of these images yourself.

src/config/images.
export default {
  defaultBgColor: "transparent",
  presets: {
    thumbnail: {
      width: 50, // size of the resized image
      height: 50, // size of the resized image
    },
    noRatio: {
      width: 474,
      // the placeholder image may have a different height than the loaded image
      // when you have a list of images but don't actually know the ratio of the final image
      // you can replace the height with placeholderHeight in the preset
      placeholderHeight: 474,
    },
    withSizes: {
      width: 1100,
      height: 1100,
      // the sizes allows the image to resize itself depending on the screen size
      // if no sizes are defined then these default sizes will be used
      sizes: ["0.5", "1", "2", "4"],
    },
  },
};