@the-ksquare-group/zanma-react-components

Component library used across Zaamna apps. It exposes reusable React components styled with styled-components, plus a theming system used by Zaamna products.

This project was originally bootstrapped with Create React App, but is now maintained as a standalone component library with Storybook 7, React 18 and TypeScript 5.

Requirements

• Node.js >= 22
• Yarn 1.x
• react 18.x and react-dom 18.x in the consuming application
• (Optional but recommended) TypeScript 5.x in the consuming application
• styled-components ^5.x

Installation

yarn add @the-ksquare-group/zanma-react-components
# or
npm install @the-ksquare-group/zanma-react-components

Component Theming

Since version 0.7.0 components handling theming through a ThemeProvider from styled-components, making neccesary that consumer applications provide the ZRCProvider exported from this project and pass an object with structure {color100: string, color200: string, ..., color800: string} to the theme prop, components will automatically subscribe to changes in this prop.

import React from 'react';
import { ZRCProvider } from '@the-ksquare-group/zanma-react-components';

const theme = {
  color100: '#...',
  color200: '#...',
  color300: '#...',
  color400: '#...',
  color500: '#...',
  color600: '#...',
  color700: '#...',
  color800: '#...',
};

export const App = () => <ZRCProvider theme={theme}>{/* your routes / components */}</ZRCProvider>;

The theme prop should have the following shape:

type ColorPalette = {
  color100: string,
  color200: string,
  color300: string,
  color400: string,
  color500: string,
  color600: string,
  color700: string,
  color800: string,
};

Components will automatically respond to changes in the theme prop.

Available Scripts

From the project root you can run:

yarn storybook

Runs Storybook 7 in development mode so you can browse components and their Docs pages in the browser (default URL is http://localhost:9009).

yarn clean

This command deletes the dist directory generated by yarn compile.

yarn compile

1. Runs yarn clean
2. Sets NODE_ENV=production via cross-env
3. Uses the Babel CLI to transpil all .ts/.tsx files inside src/ to CommonJS into dist/.

This is the command that should be executed before publishing or linking the library.

Local Development Instructions

Here we'll cover how to yarn link zanma-react-components so we can work with the local version of the project instead of a specific commit using GitLab. Follow these instructions:

In this project

After making changes to any component, we need to make sure the dist folder is up to date with the latest changes.

1. In this project (component library)

After you change any component, run:

yarn compile
yarn link

This creates a global Yarn link for @the-ksquare-group/zamna-react-components pointing to your local dist/ build.

Alternatively you can run:

yarn compile
yarn pack

This will create a tarball file in the root of the current proyect that you could install locally in your consumer app (more on that later).

After making any change(s), it's important to remember to parse everything again with yarn compile, and then run either yarn link or yarn pack.

2. In the consuming project

If you used yarn link, from the other project's root:

yarn link "@the-ksquare-group/zanma-react-components"

And if you're using TypeScript, make sure modules.d.ts has:

declare module '@the-ksquare-group/zamna-react-components';

Otherwise, if you used yarn pack, copy the absolute path from the generated tgz file and add it to your package.json:

{
  "dependencies": {
    "@the-ksquare-group/zanma-react-components": "/path/to/tgz/file"
  }
}

Then run yarn install

3. Link shared peer dependencies (React18 etc.)

To avoid having multiple copies of React and other peer dependencies,

In the project that you'll be consuming this library from

After the previous step, you should go to the project where you are using this library. This will link the specific instance of the project that has been linked, it's important to note that after making any change in the component library you should parse the components again and link them. (YES EVERY TIME)

3. run yarn link "@the-ksquare-group/zanma-react-components"

3.1 remember to declare the module in modules.d.ts, simply add declare module '@the-ksquare-group/zanma-react-components'

After linking the component library to our project, we need to create a link to the specific version of react & react-router-dom that we are using in the project. This is an important step because otherwise we would have 2 instances for each dependency, the one from our component library and the one we are using in the current project, our library should use the version of the project that's consuming it. This is only necessary for local development. So we need to access node_modules and find each folder, then we are going to create the link. Remember to return to the root of the project after this step. You only need to do this step once.

4. run cd node_modules/react && yarn link -> cd .. && cd react-router-dom && yarn link

In this project

Finally, we need to return to this project and link the instance of react and react-router-dom that we created in the other project (the previous step).

5. run yarn link react -> yarn link react-router-dom

Final Steps

Nice, these are almost all the steps to move between projects when consuming a local version of this component library! However, we are missing some important details.

• When you make any changes in zanma-react-components I suggest returning to the project where you are consuming it and run yarn unlink "@the-ksquare-group/zanma-react-components", this will delete the link we created previously from the project and will leave you open to follow the instructions above once again (steps 1 through 3).

• Finally, in this project run yarn unlink react & yarn unlink react-router-dom. You should only do this when you are done running a local version of the component library, this will unlink both instances from this project. Remember to go back to the project where you created this link in node_modules/react and run yarn unlink, do the same with react-router-dom.

• Once you removed all the links, and you are ready to commit your changes remember to run yarn clean to delete de dist folder that we created.

Publishing a new version

Releases are published to npm automatically via GitHub Actions when you create a GitHub Release.

1. Prepare the release locally

1. Make sure all changes are merged into the develop branch.
2. Update the version in package.json (following semver, e.g. 1.0.0 → 1.1.0).
3. Update CHANGELOG.md with a new section for that version.
4. Commit and push your changes to GitHub.

Example:

git add package.json CHANGELOG.md
git commit -m "chore(release): 1.1.0"
git push

2. Create a GitHub Release

1. Go to GitHub → Releases → New release.
2. Set the tag to the new version:
   • You can use either v1.1.0 or 1.1.0.
3. Select the target branch/commit (usually main).
4. Add release notes (you can copy from CHANGELOG.md).
5. Click Publish release.

3. What the CI does

The GitHub actions workflow will:

1. Check that the tag matches package.json version:
   • It reads "version" from package.json, e.g. 1.1.0.
   • It normalizes the tag by stripping a leading v (so v1.1.0 → 1.1.0).
   • If the normalized tag and package.json version don’t match, the job fails early with an error like:
     • Version mismatch – package.json=1.1.0, tag=v1.2.0
   • Nothing is published in that case.
2. Install dependencies:

   yarn install --frozen-lockfile

3. Build package

   yarn compile

4. Publish to npm bash npm publish --access public using the NODE_AUTH_TOKEN provided via secrets.NPM_TOKEN.

4. NPM configuration

Make sure:

• dist/ is ignored by git (in .gitignore), but
• dist/ is included in npm package.json:

{
  "files": ["dist/"]
}

...and that main/module/types fields point to the build files in dist/ (for example):

{
  "main": "dist/index.cjs.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts"
}