Hazelcast design system components and utilities
npm install @hazelcast/ui
Design system built with A11Y in mind. Developed as a Lerna monorepo with shared frontend libraries for a variety of Hazelcast product offerings.
Design system is available live at URL: https://5f80b6aa3ceb290022dfea61-tultjjrhhk.chromatic.com/?path=/story/getting-started-intro--page
- Installation
- Usage
- Global CSS
- SSR
- Stable IDs
- Project structure
- Automated visual regression testing
- How-to
- Install PnpM
- Setup
- Under the hood
- Deploy
- Add a new shared dependency
- Add a new local dependency (for one package only)
- Make changes to several packages and test it
- Run storybook for development
- Run linting
- Run unit tests
- Run visual regression tests
- Approve the updated for visual regression test screenshots
- Run all checks at once
- Releasing a new version
1. npm i @hazelcast/ui (npm i @hazelcast/ui@next - canary version) - set of Hive UI components
2. npm i @hazelcast/services (npm i @hazelcast/services@next - canary version) - Hive services
3. npm i @hazelcast/helpers (npm i @hazelcast/helpers@next - canary version) - Hiver helpers
4. npm i -D @hazelcast/test-helpers (npm i -D @hazelcast/test-helpers@next - canary version) - Hive test helpers
Be aware, that we compile our TypeScript code to the modern ES2018 JavaScript. To run it in legacy environment, please, configure webpack or any other bundler accordingly.
Moreover, we do not do anything about styles (scss in our case). We just import them as modules. Please, configure webpack or any other bundler to handle them.
The latest version of the design system is accessible at https://master--5f80b6aa3ceb290022dfea61.chromatic.com/.
This library is used from Next.js projects.
Individual projects should transpile @hazelcast/ui.
However, Next.js still forbids to import files with .css / .scss extension unless they're in \_app.tsx
So please make sure to import the following global styles in your projects if you need them.
``typescript`
import '@hazelcast/ui/styles/datepicker.scss'
or
`typescript`
import '@hazelcast/ui/styles/datepicker.module.scss'
if you need a CSS modules version
We use react-uid to generate stable IDs. you'll need UIDReset and UIDFork (optionally) to properly handle SSR. See the README.
packages contains a list of published packages:
- helpers (full name @hazelcast/helpers)services
- (full name @hazelcast/services)test-helpers
- (full name @hazelcast/test-helpers)ui
- (full name @hazelcast/ui)
Uses stories from Storybook as test cases. In other words, any story is going to result in a set of screenshots. Moreover, any story is required to have an associated set of screenshots. Based on Loki, which uses headless Chrome to render the screenshots in Docker.
`
npm install -g pnpm
`
pnpm i
#### Under the hood
It runs a regular pnpm install and executes a postinstall hook. In that hook it runs:
- pnpm run compile
Our child packages are written in TypeScript. To import them from in other packages they must be compiled to JavaScript first.
Every commit to master is automatically deployed new canary version of the package (@hazelcast/xxx@next) by Hazelcast Jenkins.
In the root folder run
`
pnpm add [-D] dependency-name
In the root folder run (replace @hazelcast/ui with @hazelcast/helpers, @hazelcast/test-helpers or @hazelcast/services if needed)
`
pnpm add --filter @hazelcast/ui dependency-name
When Lerna does the bootstrapping, it creates symlinks to the local packages other packages depend on. In our case, @hazelcast/ui depends on @hazelcast/helpers. Lerna is going to create a symlink ./packages/ui/node_modules/@hazelcast/helpers that points to ./packages/helpers. When we change our TypeScript code, the associated compiled JavaScript is not updated automatically. So if we change something in @hazelcast/helpers and we want to test how it works in @hazelcast/ui, we need to compile our changes in @hazelcast/helpers. To do that we have two options:
1. Compile all packages with pnpm run compile in the root directorycd packages/helpers && pnpm run compile
2. Compile a specific package, e.g.
Now we can use the updated code in @hazelcast/ui.
In the root directory
`
pnpm start
In the root directory
`
pnpm run lint
In the root directory
`
pnpm test
In the root directory
`
pnpm run build-storybook
pnpm run test:visual
Say, we have changed something in our components.
First we need to run the visual regression tests to make sure that the change affected how the component is displayed.
`
pnpm run build-storybook
pnpm run test:visual
Now, if the test suite failed, we need to go to packages/ui/.loki and manually review the screenshots in the current folder and the diff in the difference folder. If we like what we see, we need to run pnpm run test:visual:approve in the packages/ui folder. It will update the reference screenshots.
`
pnpm run verify-all
If you PR passes this check locally, it is almost guaranteed to pass it on the CI.
Assuming you're on latest master and the build is alright (pnpm run build runs without errors).
1. First we create a release branch for the next version locally (in this case v1.1.0):
`
git checkout -b release/v1.1.0
We push this new branch to Github:
`
git push -u origin release/v1.1.0
2. Then we run:
`
pnpm exec lerna version 1.1.0
This updates the package versions (in package.json, package-lock.json), creates a commit with necessary tags and pushes to Github automatically.
At this point you should create a pull request and merge the new version branch (v1.1.0) to master.
3. Now, after merging this pull request, we have the latest version available on GitHub. And it will be automatically published to npm with the required tags and releases;
Wait for a few seconds/minutes (depends on how busy npm is at the time), and you should see the latest version we just released in the list returned by:
`
pnpm view @hazelcast/ui versions
If something went wrong and npm did not create a new release, then you can manually inform it about our new release:
`
pnpm exec lerna publish from-git