Reference store Progressive Web Application in React
Branch: master
Clone or download
shaunmaharaj Fix for Issue #248 (#249)
- Explicitly set followlocation to true
Latest commit fb1777d Feb 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update Issue Template to provide info (#80) Oct 11, 2018
.vscode add carousel to the product details page Jul 12, 2018
data Remove MACOS specific directory and files (#238) Jan 31, 2019
docker Fetch configs from general source (#214) Feb 13, 2019
eam/keycloak - Create vestri theme for keycloak login UI Jan 21, 2019
src
test - Update AUT based on changes Jan 24, 2019
tools - Update License in all files Aug 16, 2018
webpack WIP: Update base url for admin API calls (#223) Jan 28, 2019
.babelrc Feature/display all sub categories (#173) Jan 9, 2019
.dockerignore Production deployment (#121) Aug 29, 2018
.editorconfig Fixed Bug reported in checkout flow Jul 25, 2018
.eslintrc Fix pipeline errors Jan 24, 2019
.gitignore Feature/facebook chat component (#141) Jan 7, 2019
Jenkinsfile Intoli script modifications to fit our Jenkins Node OS (#136) Dec 8, 2018
LICENSE - Update License in all files Aug 16, 2018
README.md update b2b ref store (#247) Feb 14, 2019
install-google-chrome.sh Intoli script modifications to fit our Jenkins Node OS (#136) Dec 8, 2018
package-lock.json - Initial push for EAM login flow Jan 19, 2019
package.json Initial B2B features (#177) Jan 16, 2019

README.md

REACT PWA Reference Storefront Quick Start Guide

Table of Contents

React PWA Reference Storefront

Documentation Introduction

This document provides guidelines for knowledgeable JavaScript developers and front-end developers to extend and customize React PWA Reference Storefront components. However, this document is not a primer for JavaScript or CSS and is intended for professionals who are familiar with the following technologies:

Related Resources

Overview

The REACT PWA Reference Storefront is a flexible e-commerce website built on Elastic Path’s RESTful e-commerce API, Cortex API. Through the Cortex API, the storefront uses the e-commerce capabilities provided by Elastic Path Commerce and gets data in a RESTful manner. For more information about the storefront, see REACT PWA Reference Storefront Documentation.

The Storefront is designed as an open source mobile Progressive Web Application (PWA) that has the capabilities for local browser storage page caching and persistent session management. This PWA is built using the 'React.js', Bootstrap, and Babel technologies. Webpack and node.js enable the application layer interactions through the configurable web server. For more information about the software requirements, see the Requirements and Specifications section.

Setting up the Storefront

Prerequisites

Ensure that the following software are installed:

Configuration Parameter Descriptions

You must configure the following parameters in the ./src/ep.config.json file:

Parameter Importance Type Description
cortexApi.path Required String The URL, which is composed of the hostname and port, to access Cortex. By default, a web proxy is configured in the Webpack configuration of the project. For local development, set this value to /cortex to redirect Cortex calls to the local proxy.
cortexApi.scope Required String Name of the store from which Cortex retrieves data.
cortexApi.pathForProxy Required String The path to which the Webpack proxy routes the Cortex calls from the storefront. This value is a URL that consists of hostname and port of a running instance of Cortex. Leave this field blank to disable proxy.
skuImagesUrl Required String The URL that consists of the path to catalog images hosted on an external CMS. Set this parameter to the complete URL of the images by replacing the sku/file-name with the %sku% string. This value is populated when the page is loaded with values retrieved by Cortex.
siteImagesUrl Optional String The path to the site content and marketing images hosted on an external CMS. Set this parameter to the complete URL of the images by replacing the filename and file extension with %fileName%. This parameter is populated with the values set in the components when the page is loaded, and uses the assets locally available in the ./src/images/site-images directory.
arKit.enable Optional Boolean Enable elements for ARKit's Quick Look capability to load on a product display page. When arKit.enable is enabled, any product images that have hosted ARKit USDZ files are wrapped with an anchor tag referencing the file hosted on an external CMS.
arKit.skuArImagesUrl Optional String The path to the USDZ files hosted on an external CMS used for ARKit Quick Look. Set this parameter to the complete URL of the files by replacing the sku/file-name with %sku%. This value is populated when the page is loaded with values retrieved by Cortex.
b2b.enable Optional Boolean The general configuration to enable the B2B e-commerce shopping flow components in the storefront.
b2b.authServiceAPI.path Optional String The URL, which is composed of the hostname and port, to access the Admin APIs. By default, a web proxy is configured in the Webpack configuration of the project. For local development, set this value to /admin to redirect Cortex calls to the local proxy.
b2b.authServiceAPI.pathForProxy Optional String The path to which the Webpack proxy uses to route Cortex calls from the storefront to the publically hosted Account Management service. This value is a URL consisting of a hostname and port of a running Cortex for Account Management service instance. Leave this field blank to disable proxy.
b2b.keycloak.callbackUrl Optional String The URL that is passed to keycloak, and redirected to upon a successful login.
b2b.keycloak.loginRedirectUrl Optional String The keycloak log on URL.
b2b.keycloak.logoutRedirectUrl Optional String The keycloak log off URL.
b2b.keycloak.client_id Optional String The keycloak client configuration ID. Set this value to the identifier of the client configured in keycloak for the storefront. A default configuration is preset, however older environemnts may use eam. For more information, see the Deploying and Configuring Keycloak section.
gaTrackingId Optional String The Google Analytics tracking ID to integrate with Google Analytics Suite to track enhanced e-commerce activity on the site.
indi.enable Optional Boolean Enable the integration component for Indi. More information may be found available here https://indi.com/.
indi.carousel Optional Values Configurations for the Indi carousel component.
indi.productReview Optional Values Configurations for the Indi product review component.
indi.brandAmbassador Optional Values Configurations for the Indi brand ambassador component.
facebook.enable Optional Boolean Enable the Elastic Path Facebook Chatbot component. More information may be found available here https://github.com/elasticpath/facebook-chat.
facebook.pageId Optional String The Facebook Page Identifier used to connect the chatbot component to Facebook.
facebook.applicationId Optional String The Facebook Application Identifier used to connect the chatbot component to Facebook.

Configuring Sample Data

Elastic Path provides a set of sample data with the storefront project.
Note: A valid Elastic Path development environment is required to access the sample data.

  1. From the react-pwa-reference-storefront/data directory, extract the sample catalog data contents into the ep-commerce/extensions/database/ext-data/src/main/resources/data directory.
  2. In the ep-commerce/extensions/database/ext-data/src/main/resources/data/ directory, update the liquibase-changelog.xml file with the following sample data:
    <include file="ep-blueprint-data/liquibase-changelog.xml" relativeToChangelogFile="true" /> Note: This data must be the only sample data included within the sample data block.
  3. In the ep-commerce/extensions/database/ext-data/src/main/resources/environments/local/data-population.properties file, set the liquibase.contexts property to default,ep-blueprint.
  4. In the command line, navigate to the extensions/database module.
  5. To run the Data Population tool, run the following command:
    mvn clean install -Preset-db. For more information about populating database, see the Populating the Database section.

Setting up a Development Environment

  1. Clone or pull the react-pwa-reference-storefront repository to your directory.
  2. Run the cd react-pwa-reference-storefront command.
  3. To install dependencies, run the npm install command.
  4. Configure the ./src/ep.config.json file as required for the environment.
    For more information, see the Configuration Parameter Descriptions section. Note: For more information about configuring the storefront as a B2B instance, see REACT PWA Reference Storefront Documentation B2B.
  5. To start the server in development mode, run the npm start command.
  6. To see the running Progressive Web Application (PWA), navigate to http://localhost:8080/ .

Setting up a Production Environment

  1. Clone or pull the react-pwa-reference-storefront repository to your directory.

  2. Navigate to the react-pwa-reference-storefront directory.

  3. Add custom configurations to the Docker file, Docker compose file, and Nginx configuration file, if any.

    1. Provide any custom configurations you would like passed into your Docker container at runtime into src/ep.config.json by replacing the values of any parameter with a custom configuration value.
    2. Provide any custom configurations you would like passed into your Docker container at runtime directly below the existing RUN jq command. One has been provided to you as an example.
      Note: Use the jq syntax for the command. For more information, see the jq manual. Ensure that you add the NGINX_REPLACE_ prefix for the custom configurations.
    3. Update the ./docker/prod/nginx.conf file with the new configuration by adding a new sub_filter statement within the configuration block below the existing configuration. Use a generic value, which is used for the environment variable in the next step, for the configuration.
    4. In the ./docker/prod/docker-compose.yaml file, add the environment configuration variable within the environment block and set a value to add in the container.
  4. Build a Production Docker Image by performing the following:

    1. Run the docker build -t ep-store -f ./docker/prod/Dockerfile . command.
    2. Push the ep-store image to the Docker repository.
  5. Run a Production Docker Image, by performing the following:

    1. Navigate to the docker/prod/ directory.
    2. In the docker-compose.yaml file, update the following parameters:
    Environment Configuration Value
    $DOCKER_REPO ep-store
    $CORTEX_URL The Cortex server URL
    $AUTHSERVICE_URL The Cortex Account Management service URL (This is required for all scenarios. If not running the storefront in B2B mode, you may set this to the same value as $CORTEX_URL).
    $DOMAIN The domain name without http://
    $SSL_CERT_PATH The certificate file path in the remote server.
    For example, /etc/letsencrypt/live/reference.elasticpath.com/fullchain.pem.
    $SSL_KEY_PATH The path of the private key in the remote server.
    For example, /etc/letsencrypt/live/reference.elasticpath.com/privkey.pem.
    Note: You can use the certificate generated by any certificate provider, such as Let's Encrypt.
    $CORTEX_API_SCOPE The name of the store from which Cortex retrieves data
    1. To start the Docker container created for the Docker image, run the following Docker command:
      • docker-compose up -d

Running a Linter

The storefront project is set up with the linting utility, ESLint. For the storefront project, Elastic Path uses and extends the ESLint configuration provided by Airbnb. For more information on the style guide, see the Airbnb GitHub page.
By default, the ESLint loader is added to the webpack.config.dev.js file. When you start the application in the development mode, the ESLint loader automatically runs.

  1. To run the linter from the command line, navigate to the project root directory.
  2. Run the following command: ./node_modules/.bin/eslint --ext .js --ext .jsx [file|dir|glob]
  3. Run the following command for the entire project: ./node_modules/.bin/eslint --ext .js --ext .jsx . With the ESLint extension for Visual Studio Code, you can view feedback when you write the code in the Problems view.

Note: When you check in the code, ensure that all linting errors are resolved.

Adding New Locales

The reference storefront supports multiple languages and currencies. Add all front-end textual data in the localization/en-CA.json file as a resource string. By default, en-CA and fr-FR locales are provided in the project.

  1. For development purpose, run:
    node tools/translate.js.
    This runs a pseudo translation from en-CA locale to fr-FR.
  2. To add a new locale, add an entry to the supportedLocales array in the ep.config.json file and add an appropriate .json file to the localization folder.
  3. Configure the language and currency for all products in Commerce Manager.

Running Unit Tests

Test data are provided in the tests directory.

  1. To run all tests, run the following command:
    mvn clean install -Dcucumber.options="--tags @smoketest"
  2. To run sanity test, run the following command:
    mvn clean install -Dcucumber.options="--tags @sanity

Maven Options to Run the Unit Tests

Option Description
-Dcucumber.options="--tags @smoketest" Specifies that you can replace the tag with a tag that you define.
-Dfailsafe.fork.count="<no of testes>" Specifies the number of tests that can be run at the same time. The default value is 1. You can change this value depending on number of TestsIT classes.
-Premote -Dremote.web.driver.url="<REMOTE DRIVER IP>" Specifies that the tests are executed using a remote VM. The remote.web.driver.url attribute specifies the URL of the remote VM. For example, http://<IP_ADDRESS>:4444/wd/hub.

Note: You must set up the selenium grid to use this feature.For more information, see Selenium documentation.

Running Subset of Tests

  1. In the /selenium/src/test/java/com/elasticpath/cucumber/ module, right-click a TestsIT class and click Run. You can create your own local runner class to run your own tagged tests. For example, RunLocalTestsIT.java runs your own tagged tests at local. Note Do not commit the local runner class and tags that are only for the local testing purpose.

Updating browser driver versions

  1. Download the latest browser driver and update the /selenium/src/test/resources/RepositoryMap.xml file with the driver version.
  2. Update the RepositoryMap.xml with the bash value of the browser driver:

Configuring Jenkins Pipeline

The storefront project includes a Jenkinsfile template to configure a Jenkins job to build a Docker image for store from the project, deploy the Docker image to AWS, and run the unit tests.

Prerequisites

  • Ensure that an AWS EC2 instance is created for the pipeline to deploy the store and Cortex.

Configuring the Jenkinfile

  1. Open the Jenkisfile included in the project directory.
  2. Configure Jenkins job with the required parameters as described in the Jenkins Pipeline Parameter Descriptions section.
  3. Save the changes.

Jenkins Pipeline Parameter Descriptions

Parameter Description
DOCKER_REGISTRY_ADDRESS The path to AWS ECR. For example, ${awsAccountID}.dkr.ecr.${region}.amazonaws.com.
CORTEX_NAMESPACE The namespace for the Cortex images, such as Activemq, batch server, integration server, search server ,and Cortex server.
DOCKER_IMAGE_TAG The tag used for the Cortex images.
STORE_NAMESPACE The namespace for the store image and database image.
STORE_IMAGE_TAG The tag for the store images, which are store image and database image.
STORE_NAME The name of the store. For example, vestri.
EC2_INSTANCE_HOST The IP address of the AWS EC2 host to deploy Jenkins pipeline.
EC2_INSTANCE_USER The user credentials of the AWS EC2 instance.
EC2_INSTANCE_SSH_KEY The path in Jenkins node that redirects to ec2.pem file.
SOLR_HOME_GIT_URL The git URL to the project containing the solr home configuration.
SOLR_HOME_BRANCH The branch name of the solr home configuration.
SOLR_HOME_PATH The path to the solr home configuration that is provided in the git project.

Configuring the Jenkins Job

  1. Navigate to the Jenkins job console and select the Jenkins job to configure.
  2. In the left pane, select Configuration.
  3. In the Build Triggers tab, select Poll SCM.
    The Schedule field is displayed.
  4. In the Schedule field, set the time to run the job periodically.
    The default setting is 1 min.
  5. In the Advanced Project Options tab, do the following:
    1. In the Definition field, select Pipeline script from SCM.
    2. In the SCM field, select Git.
    3. In the Repository URL and Branches to build fields, enter the appropriate settings.
    4. In the Script Path filed, select Jenkinsfile
  6. Click Apply.
  7. Click Save.

You can configure all other setting as required for the project. This Jenkins job triggers commits to the master at the scheduled time. For more information about the pipeline, see the Jenkins Pipeline Workflow section.

Jenkins Pipeline Workflow

When you run the the Jenkins job, the job operates in the following sequence:

  • SETUP - Pulls the project and the project containing solr home configuration to a repository.
  • BUILD - Builds the store Docker image from the docker/dev/Dockerfile directory in the project and pushes the changes to AWS.
    • The development Docker runs the entrypoint.sh script to replace the path to Cortex and the store in the ep.config.json file and starts the project in development by running the npm start command.
  • UNDEPLOY_EXISTING - Cleans up the working directory and removes docker containers and images, if any.
  • DEPLOY - Creates the working directory, copies the files from the project and solr home configuration, exports the environment variables used in the compose file, and deploys the store and Cortex with Docker-compose.
  • TEST - Sets the environment variables for JAVA_HOME and adds Java and Maven to the path. The variables are pulled from the Jenkins tools. For headless tests, installs Google Chrome by running the script at intoli and downloading google-chrome-stable and renames it to google-chrome to enable chromedriver to find it for tests. Before you run the tests, replace the selenium.session.baseurl in the pom.xml. For viewing reports in Jenkins UI, Jenkins Cucumber plugin is used.

Terms And Conditions

  • Any changes to this project must be reviewed and approved by the repository owner. For more information about contributing, see the Contribution Guide.
  • For more information about the license, see GPLv3 License.