@bloomreach/babujs

---

Babu.js

This is a component shared library build in React. All the components are generic and can be used in any React application. The main goal of this library is to standardize the look and feel across multiple apps and to enable fast development.

Local Development

Prerequisites

• Node.js 18.x
• NPM 9.x

Setup

• Run npm run start
  • This will build the library and start the Storybook demo at http://localhost:6006/
  • Code changes to components or component stories will be hot-reloaded
• Add a new component
  • ./src/components/<brComponentName> Add your component brName.tsx
  • ./src/components/<brComponentName> Add unit tests for the new component
  • ./src/components/index.ts Add your component export
  • ./stories/components/<brComponentName>/brName.stories.ts Add a stories to the new component
• Change an existing component
  • If a component is not a Typescript component try to convert it to the Typescript
  • If a component doesn't have unit tests add them or cover the new changes in already existing tests
  • If a component doesn't have stories add them or cover the new changes in already existing stories, the component stories are located in the following place /stories/components/<brComponentName>/brName.stories.ts

Development setup when using the library in an external project (as a dependency)

More often than not, you will find yourself needing to make changes both to an app. as well as the library. For such a development setup we make use of Yalc which creates a symlink between the library repository and the dependent repository.

• Install Yalc globally
• Navigate to your Babu.js directory and run yalc publish
  • This will create a package with the Babu.js changes and add it to do Yalc store
  • If successful, you should see a message similar to @bloomreach/babujs@<version> published in storein the terminal
• Navigate to your dependant app.
  • Run yalc add @bloomreach/babujs@<version>
  • You can start the dev runner on parent package npm run devserver
• Every time you make changes in Babu.js, you need to update the package in the store
  • In the Babu.js directory run again yalc publish
  • In the Maple directory run yalc update @bloomreach/babujs@<version>
• Additionally to Yalc, you could publish a beta version with your changes to npm using the command npm publish --tag beta, and use that beta version in your app.

Publishing

Publishing a new version of the library is automated through GitLab and should be, for all effective purposes, the responsibility of nobody else but GitLab. You should never publish a non-beta version of the library from your local machine.

• Update the library version in the package.json file
  • The version strategy for the package is as follows:
    • If your planned changes contain only Bug/Security fixes then run npm version patch
    • If your planned changes contain New/Update components then run npm version minor
    • If your planned changes contain Breaking changes then run npm version major
• Create a merge request targeting the main branch
• Ask for code review. At least 1 approval (other than yourself) is required
  • Once approved, merge your branch into the main branch
• Publishing the new library version will be done automatically by the pipeline
  • If a new version of the library has been merged, the pipeline will publish the new version to npm.
  • If the library version matches an existing version, nothing will happen

Storybook

A new version of the storybook will be created and deployed by merging changes into the main branch. The online instance of the storybook will be available at https://babujs.prod.br-engops.io

Unit tests

The Vitest unit test framework is used for the unit testing. The unit test files should end with *.spec.ts and place close to the component or module which is going to be tested.

End-to-end tests

The Playwright test framework is used for end-to-end testing. All tests are located in the root folder tests/**/*.spec.ts.

Visual regression tests

Currently, end-to-end tests contain only visual regression types of tests based on old demo pages. All the old demo pages have been converted into storybook stories, check stories/demo-pages. It is not complete stories as they should be in the storybook it is the old demo pages rendered inside the storybook. The main purpose is to use them as a reference in visual regression testing. The visual regression tests for the demo pages located in the tests/visual-regression/demo-pages.spec.ts file.

IMPORTANT

Those tests are used only as a first step during the transition to the full unit/e2e test coverage for components. Don't rely on them as final QA guards. Instead of putting effort to support them better write complete unit/e2e tests and add a story for each component.

Run e2e tests

• Use the command npm run e2e to start end-to-end tests inside the Docker container (the docker and docker compose should be installed on your machine).
• When tests are done check the Playwright output in the console if some of the tests failed use the following command to open the Playwright report: npm run e2e:report

Update failed visual regression tests

• If the failure appeared in the visual regression tests and those changes are correct, please update the existing reference images with the following command: npm run e2e:update. The Playwright will generate new correct reference images which should be committed to the repository

End-to-en tests setup for CI and local development

All e2e tests run locally in Docker container based on the official image, see Playwright documentation for more details. Tests run inside the Docker container to keep a predictable environment for each developers and CI. CI setup its own job based on the same Docker image and almost repeat the same commands as it done in docker-compose.yml file.

IMPORTANT

Please, be aware that in case of any changes in the CI setup for the e2e tests job, see .gitlab-ci.yml they should be applied to the local setup in the docker-compose.yml and vice-versa.

Archive old versions of the library

This process should be only done when updating the library to a mayor release.

• Create a new branch based on the current main branch and name it as follows .x. Like for example 1.x, 2.x, 3.x and so on. This is very important, so please make sure the branch name follows this convention
• The release process is automated in the same way as the main branch. Only difference is that merging changes into these branches won't create or deploy a new version of the storybook. That's because we want to keep the storybook in sync with the latest library release
• These branches will be used only for fixing bugs and security issues. The main purpose of these branches is to deal with urgent issues awhile all apps are updated to the latest library release