Decoupled-front-end NPM

Cauldron

React Component library for the front end of Secret Escapes. Uses the components of Falcon library as building blocks, and handles more complex functionality, connecting to state and using the GraphQL API.

For more info check the Wiki page Decoupling on the Front End

If you don't want to develop in Cauldron, and you simply want your local development Flashsales version to import Cauldron locally, go through the Pre-requisites and then move to [2. Developing Flashsales and using Cauldron as an asset](#2.-Developing-in-Flashsales-and-using-Cauldron-as-an-asset)

Development tips and guidelines

Check the Wiki page How to implement a component

Pre-requisites

Install Yarn
Install Docker
Login to NPM in order to download private package dependencies. You can find the NPM credentials in Bitwarden, under entry "NPM registry". (If you don't have access to Bitwarden, send a request to Tech support).

npm login

Then follow instructions on screen.

1. Developing in Cauldron

Run tests

yarn test

If you have Flashsales running localy and using local Cauldron, and you want to see how changes made in Cauldron affect Flashsales, you can use

yarn watch

This command watches for code changes in Cauldron and if any, rebuilds assets, exposes new version via https and reloads Flashsales site in browser. Keep in mind that it requires npm ecosystem to be installed, so if you just develop Flashsales, see point 2)

If you don't know how to point Flashsales to local Cauldron, check end of section 2.

View components in Storybook

For individual component development and review, you can view your components in Storybook.

yarn storybook

2. Developing in Flashsales and using Cauldron as an asset

If you want to see Cauldron as a javascript asset integrated in local Flashsales, you need to run a script in Cauldron, which builds a local server and serves the script in the following url (https://localhost:54321/assets/fe/development/secret-escapes-frontend.min.development.js). When flashsales local development version runs, it looks for the script in that url and imports it.

If this is the first time running the script then you need to change the permissions.

chmod +x localDevelopment.sh

Then run

./localDevelopment.sh

This will:

Delete the existing dist folder containing existing build files if it exists.
Run yarn build to build the current code.
Stops and deletes the existing docker container if it exists.
Deletes the existing docker image if it exists.
Builds a new docker image. The image is an httpd server which serves the built files from the dist folder.
Runs the docker image on port 54321.

Open the following link to load the js file in the browser: https://localhost:54321/assets/fe/development/secret-escapes-frontend.min.development.js Your browser might complain about self signed certificate. It is important to confirm that cert in order to see properly rendered pages in locally run flashsales.

By default, flashsales will use the production version of Cauldron even for local environment. If you want to use a local version of Cauldron on flashsales you need to prefix the grails command with "LOCAL_CAULDRON=true" when you run flashales. For example "LOCAL_CAULDRON=true grails run-app -https". By doing so, the dynamic config and the cdn uri will be changed to point to your local server.

3. Developing in parallel with Falcon

If you want to make changes in Falcon while developing locally, and see these changes in Cauldron, you can link Falcon. In order to do so:

Clone Falcon locally
Inside Falcon folder

yarn link
yarn build

hint: build:prod compiles faster than build

Inside Cauldron folder

yarn link @se-admin/falcon
yarn

When you make changes in Falcon, you'd have to run yarn build inside Falcon folder, for those to appear in Cauldron.

If you want to unlink Falcon, and use the version from NPM registry

Inside Cauldron folder

yarn unlink @se-admin/falcon
yarn

We get strange errors sometimes, while building Cauldron. They related to cache, integrity etc. In such cases you can try a script that is like nuke bomb - unlinks falcon, refreshes as much as we can, downloads 500 MB of libs again but hopefully fixes any issues with your env

4. Integrating with Sparrow

Sparrow is the GraphQL server from where Cauldron fetches data, so if you need to work on any component requiring data from Flashsales, you will need Sparrow. Just follow instructions on Sparrow repo for this.

5. Staging env with your Cauldron branch

A deploy staging job allows to provide branch of Cauldron as parameter. If you leave it empty - a recently released master branch will be used by staging (from https://s3.amazonaws.com/static.secretescapes.com/assets/fe/MAJOR_VERSION/head/cauldron.min.js). If you put there a branch name (including master name, if you need to use not yet prod released master branch) - Cauldron asset from S3 will be used, for instance https://s3.amazonaws.com/static.secretescapes.com/assets/fe/undertest/DEV-41864-bundle-splitting-moment-slimming/cauldron.min.js You need to publish the asset to S3 by publishing your Cauldron branch selecting TARGET_ENV as Staging or test (see 'Implementation and pull requests process' section below) If you did Falcon changes and your staging's Cauldron requires changed Falcon - remember about published Falcon first.

Deploy Storybook to AWS S3

You can deploy the storybook to S3, in order to show it to other people in the organisation.

Prerequisites

Give permissions to the script chmod +x scripts/deploy-to-s3.sh
Contact Tech Support to get permissions to add content to S3 bucket (s3://static.secretescapes.com/frontend/cauldron-storybook/)
Have the AWS CLI installed and configured in your system.

Usage

yarn deploy:storybook

This will automatically deploy your storybook to S3, and it'll be available under the link https://s3.amazonaws.com/static.secretescapes.com/frontend/cauldron-storybook/{BRANCH_NAME}/index.html

Implementation and Pull Request process

Check the detailed guide How to implement a component

Specs for visual/design changes should be given by a designer, before starting with the development.

Also, before asking for a Code Review, a design approval needs to be taken, by asking the designer of the team to see the changes and confirm that they're OK. Then, code review needs to be done.

If Cauldron tests are passing, and the reviews are done, you can merge and release Cauldron. Note that every merge into master must be followed by a release, even if the component is not yet being used in Flashsales.

Release

The release is done thorugh a Jenkins job. This job has few parameters. Which to fill depends on env you deploy to. If you deploy just for staging/tests needs - you need to fill only first 3. If production, also JIRA_TICKET is required.

TARGET_ENV: Dropdown with two options "Production" and "Staging or tests". It's self-explanatory, just select the environment you want to publish to.
CAULDRON_BRANCH: Name of the branch you're going to release.
CAULDRON_VERSION: Dropdown with three options "Major", "Minor" and "Patch". Major releases requires Flashsales to be amended accordingly and blocks Cauldron release queue till Flashales is released. Minor and Patch does not have any technical meaning, just semantics.
JIRA_TICKET: Comma separated list of ticket IDs. They will be sent to release channel in Slack when the release is done, in the format "Cauldron version: x.y.z JIRA_TICKET has just been released by Author". All of them will be linked to one fixVersion in Jira while production release

RELEASE_NOTES - While production release, the mail with release notes is sent. You can fill notes directly in Jira tickets, but also possible to fill here - release process will take care of putting them into Jira tickets

MAIL_RECIPIENT - Any production release triggers email with release notification. Here you choose who should receive email. Tech internal releases, without business impact can be sent just to tech.

Mail sending process contains 3 steps: 1) preview email sent just to you, 2) confirmation that all is good with email, 3) rolling out the email to all recipients In order to confirm that generated email is fine, you need to click proceed button

The integration of a component into Flashsales is a separate part of the effort, which will be done in coordination with changes on the Flashsales application itself, and will normally be handled in different JIRA tickets than the ones for the actual React implementation.