Skip to main content
Version: 2.x

Installation

Front-Commerce is a Node.js server that will serve a GraphQL endpoint and a React application to your customers. In order to run it, you need to make sure you have `npm` and `node` installed on your machine in a supported version.

Requirements​

Front-Commerce is a closed source product. This documentation supposes that you have access to our private repositories.

Access is granted to teams that have signed the relevant legal contracts, either as a Partner or a Customer. Please contact us if you need help or further information.

Important

you can find an exhaustive list of requirements and versions supported by Front-Commerce in our release notes.

You can check your versions by running these commands:

npm -v
node -v

If you don't have the minimum requirements, please follow the instructions on Node.js website.

Installation using the skeleton​

This is the recommended way to start a new Front-Commerce project.

Front-Commerce’s skeleton repository provides a quick way to get started with Front-Commerce with sane default configurations.

Get the code​

In order to install the skeleton, you need to follow these instructions:

git clone --depth=1 git@gitlab.blackswift.cloud:front-commerce/front-commerce-skeleton.git
cd front-commerce-skeleton
npm install

Depending on your internet connection, feel free to grab some tea and a cookie…

Configure the project​

The skeleton comes with default values for most of the configuration. Below are the configurations you will most likely have to change/create.

Configure the instance​

.front-commerce.js must be configured to enable module(s) matching your eCommerce backend. The skeleton is configured by default for Magento2.

To interact with Magento1, you need to change .front-commerce.js to import the Magento1 module instead of the Magento2 one.

module.exports = {
  name: "Front-Commerce Skeleton",
  url: "http://localhost:4000",
  modules: ["./src"],
  serverModules: [
    { name: "FrontCommerce", path: "server/modules/front-commerce" },
-    { name: "Magento2", path: "server/modules/magento2" }
+    { name: "Magento1", path: "server/modules/magento1" }
  ]
};
info

It's also possible to connect your Front-Commerce instance to BigCommerce.

Configure the environment​

Front-Commerce uses environment variables for runtime configurations depending on the instance that runs (local, staging, production).

Copy the .env.dist sample file to a local .env and adapt uncommented configurations. See the next paragraph to uncomment other configurations depending on your context.

Configure remote services​

Front-Commerce can interact with remote headless services. But for security reasons, most services use some tokens to ensure that you are the only one to access to their data. It also is a way to allow remote services to invalidate Front-Commerce’s cache securely.

These kind of tokens are configured as environment variables (according to one of the 12-factor app principles).

We invite you to dig into the remote services configurations and tweak them if you wish.

Configure stores​

Configure the project by creating a src/config/stores.js file. It should be an object with store codes as keys and configurations as values.

Here is an example:

module.exports = {
  default: {
    locale: "en-GB",
    currency: "EUR",
    default_country_id: "GB",
    url: process.env.FRONT_COMMERCE_URL,
    countries: (IsoCountries) =>
      IsoCountries.registerLocale(require("i18n-iso-countries/langs/en.json")),
  },
};

See Configure multiple stores for further information.

Platform specificities

When using Front-Commerce with Magento, store codes must match Magento store view code.

Optionally configure the caching strategy​

To enable caching locally, you can configure it in src/config/caching.js. For now only redis is supported, which requires to have a redis instance to connect to.

See our caching section to know more about caching in the GraphQL middleware.

Launch the application​

Launch your Front-Commerce project in development mode by running:

NODE_OPTIONS=--openssl-legacy-provider npm run start

Open http://localhost:4000 to view it in the browser. You can also open http://localhost:4000/playground to explore the GraphQL schema and interact with its data.

info

The project will reload automatically in most cases upon a source code change. However, when you are trying to override a file that already exists in one of your modules, remember to restart this script.

Bonus: launch Storybook, our UI Development Environment​

Front-Commerce is component based, and uses Storybook to allow developers to focus on building components in isolation.

Storybook is a separate application that will render all the stories written in your codebase so you can browse them. To launch it run the following command:

NODE_OPTIONS=--openssl-legacy-provider npm run styleguide

You can now open http://localhost:9001/ and explore the existing components.

tip

You can configure which stories to display in your styleguide by setting the styleguidePaths key in your .front-commerce.js file. Its value should be a list of regexes (e.g: [/.*.story.js$/];) that will be matched against your stories paths.