@caspeco/casper-ui-library

Caspeco's UI component library, built on top of on top of Chakra UI.

👉 The usage documentation can be found at https://caspeco.github.io/casper-ui-library

Local development

To build this project you need to have Node.js installed.

Commands

All commands are run from the root of the project, from a terminal.

| Command | Description | | ------- | ----------- | | npm install | Install dependencies. | | npm run dev | Build a local development version of the entire library, compiled into a single .js file for improved HMR. Automatically rebuilds when the file contents change. | | npm run build | Build the library as it will be shipped on npm. Does not automatically rebuild when files change, but you can still use this build output to verify your changes in the documentation website or in another project. | | cd ../docs && npm run dev | Starts the documentation website. Usually you want to run this alongside the library in dev mode, so open a new terminal for this. See /docs for more info. | | npm run test | Run unit tests. | | npm run test:visual | Run visual regression tests using Playwright in Docker. Automatically starts/stops Docker container. | | npm run test:visual:ui | Opens the HTML report viewer for visual test results. | | npm run test:visual:update | Update visual regression baseline screenshots. Run this after intentional UI changes. | | npm run lint | Run linting with @caspeco/eslint-config. If you use the recommended ESLint VSCode extension you can see your eslint errors directly in your editor without having to run this. | | npm run prettier:fix | Reformat all files with @caspeco/prettier-config. If you use the recommended Prettier VSCode extension you can have your files automatically formatted on file save. |

Preview locally in another project

1. Build local development version (see above).
2. In the consuming app, run npm install --no-save ./relative/path/to/this/directory (no trailing slash).
   • For example: npm install --no-save ../../casper-ui-library/packages/casper-ui-library

Now when you make a change in the component library, it should rebuild automatically and the consuming app's HMR should kick in and reload the page (preserving state is not possible as the entire library is rebuilt).

To unlink again you just need to run npm install in the consuming app. If it fails, you may need to delete node_modules first.

If you get an error about duplicate react versions, make sure this is in the vite.config.ts in the consuming app:

import path from "node:path";

export default defineConfig({
	// ...
	resolve: {
		alias: {
			react: path.resolve("./node_modules/react"),
		},
	},
});

Visual Regression Tests

Visual regression tests catch unintended UI changes by comparing screenshots of component variants to committed baselines in __screenshots__/. They run with Playwright in Docker to ensure consistent rendering across different development environments and CI.

Requirements: Docker must be installed and running.

Running tests:

• npm run test:visual - Runs all visual tests
• npm run test:visual:ui - Opens the HTML report viewer
• npm run test:visual:update - Updates baseline screenshots after intentional UI changes

[!TIP] CI fails but local passes?

1. Go to the visual-tests job in GitHub Actions
2. Download and extract the HTML artifact under the Upload visual test report step
3. Run npx vite preview --outDir . in the extracted directory to see diff report from CI

You may need to tweak the pixelmatch comparator options if you see false positives due to anti-aliasing or sub-pixel rendering differences. See existing tests for examples.

Contributing

1. Make sure your repository is up to date.

   git pull

2. Create a new branch and make your changes there. Preferrably use a branch name that includes any related Jira issue and some short descriptive name.

   git checkout -b UTF-837-add-checkbox-component

3. Make your changes.
4. Bump the version field in package.json (following Semantic versioning) and run npm install. The version reflects API changes only (e.g. removing a prop → MAJOR, adding a prop → MINOR, no public API changes → PATCH). UI changes are NOT API changes.
5. Open a pull request using the template and assign a reviewer.
6. If the PR makes significant changes to the UI (e.g. changes the sizes for all buttons), clearly announce this in the Mattermost channel.
7. After approval, merge the PR. If you have a new version in package.json it will automatically publish your changes to npm. The documentation website is always rebuilt.