Cyberport Algolia Components

Summary

• About
• Quick start
• Further info
• References

About

This repository contains the component library used for the integration of Algolia Search with the Cyberport e-commerce.

The components were developed using React, Typescript for strong type, the concepts of the Atomic Design for structuring the components, jest and testing library for tests, preferably using TDD, StoryBook as a component showcase that can also serve as a sandbox for manual testing.

Last, the implementation uses the Algolia React library, react-instantsearch-dom, which offers generic components and higher-order components (HoC) for making easier the customization of the search experience, accordingly to the client UI specifications.

Releases

| Version | Release Notes | | :-----: | ------------------------------------------------------------------------------------------------------------------------------- | | 1.0.0 | Includes the SearchBar, SearchResultsPage and all dependent components. This version was integrated using Client-Side rendering |

Quick start

Requirements

NodeJS

This library uses NodeJS, therefore if you still don't have it installed, follow the steps from the official NodeJS website. Alternatively, the Node Version Manager (nvm) might be a better option, so it is possible to install or update the NodeJS versions in an easier way.

Setup the Environment Variables File

dotenv package is in place for handling the environment variables for local development.

In the source code there is a .env.example file, which shows the skeleton of what is expected. Copy this file and name it as .env at the project root. Afterwards add the missing variables related to Algolia:

ALGOLIA_API_KEY=
ALGOLIA_APPLICATION_ID=

These values can be found in the Algolia dashboard as follows:

• Algolia application ID
• Algolia API key

Notes:

• ALGOLIA_API_KEY corresponds to the PUBLIC key. Make sure to grab the one labeled as Search API Key, as this is the one that can be shared publicly.
• The Algolia Admin key should never be used, as this key gives full access to the indexes and if leaked will generate a big security issue.
• Never commit the .env file or add the public API keys in the .env.example, as this will be part of the git history. The Algolia API public key gives READ ONLY permissions, however it is not recommended to keep it in the VCS.ß

Install dependencies

npm i

After having the dependencies installed and the environment variables setup, the development environment should be ready to go.

The following scripts are helpful for the development process:

• storybook
• test:watch
• lint and formats

The next topics will show the available npm scripts and the respective explanations.

StoryBook: Components Showcase

npm run storybook

Then open the URL: http://localhost:6006

Tests

To execute all the test suites, use the following command:

npm run test

If it is desirable to test only the files that were changed, use instead:

npm run test:watch

This command is very helpful during development time, as it will keep watching the changed files and only execute the tests related to these files.

Lint, Type check and Format

These commands are responsible to make sure that the code is following the source code defined rules (lint), do not have type inconsistencies based on the Typescript compiler (Typecheck), and has the right format based on the Prettier setup (prettier).

To run all of them together once, use:

npm run lint && npm run typecheck && npm run format:check

To fix lint and format errors automatically use instead:

npm run lint:fix && npm run format

Hint: Always run these commands before the commit and pushing your code to remote.

Build

To build the project there are three options:

• Build Components

npm run build:components

Use the above script to build the component library. This will generate the bundle file that will be further used by the Cyberport webshop - existing AEM application. If the COMPONENTS_NODE_ENV environment variable is set to development, it will generate a bundle not optimised for production, however it is good for development purposes, and so for debugging.

When the value is setup to production, it will create an optimised version of the bundle, doing minification and further optimisations. This value is used by the CI / CD process, when deploying the library to the CDN.

• Build StoryBook

npm run build:storybook

The storybook build option generates the storybook showcase application. The storybook application is available in the following internal URL: https://storybook.eu-central-1.ops.aws.csdevops.io/, so that the QA and Design teams can try and test the components. The deployment happens during the continuous integration process.

• Build All

The following command will build the library and the storybook all at once.

npm run build

Continuous Integration

Running the CI script will execute the Continuous integration steps, running multiple scripts already mentioned in this document as lint, format:check, typecheck, test, build, and so on.

This is the script executed by the CI/CD flow from Cyberport.

npm run ci

Further info

Further information about this project is available at Cyberport Confluence page

References

• Algolia Docs
• Algolia React InstantSearch
• Typescript
• React
• Atomic Design
• Jest
• testing library
• Test Driven Development,
• StoryBook