How to contribute

Prerequisites

• Node.js v20
• pnpm v8 to manage packages and dependencies
• storybook for rapid UI component development and testing
• changeset for changes documentation, changelog generation, and release management.

Scripts

Root directory

• pnpm install: bootstraps the entire project, symlinks all dependencies for cross-component development and builds all components.
• pnpm build: run build for all component packages.
• pnpm release: publish changed packages.
• pnpm storybook: starts storybook server and loads stories in files that end with .stories.tsx.
• pnpm gen:embedded-story: generate embedded story for documentation.

packages/uikit

• pnpm build:icon: generate react components from all svg files in packages/uikit/src/icons/raw and save to packages/uikit/src/icons/react.

packages/documentation

• pnpm dev: start the local dev server for documentation.
• pnpm build: run lint and build the documentation.

Developing

Run pnpm i && pnpm build && pnpm storybook to start the project in development mode.

Your working area is uikit and stories. Once you finish your coding in the uikit, please write some stories for testing.

Icons

To add new icons, you can put the svg file to packages/uikit/src/icons/raw folder then run pnpm build:icon under packages/uikit directory to generate the react component.

It will also update the import entry in packages/uikit/src/icons/index.ts. Note that you should always use the script to update it and avoid manually modifing the import entry file.

The icon script will

• scan all the svg icon in packages/uikit/src/icons/raw folder
• Rename all the svg file to PasCal case (or upper camel case)
• Use svgr to generate correspondent react jsx code to packages/uikit/src/icons/react folder
• Use a custom code template to support other props such as size
• By default, it will skip if there are already a jsx file with same name, unless you pass a --force flag

Developing documentation

After installing dependencies with pnpm install, cd to packages/documentation, create a .env file with following content:

NEXT_PUBLIC_STORYBOOK_HOST=https://tidbcloud-uikit-story.netlify.app/

# if you want to reference your local storybook, set to
# NEXT_PUBLIC_STORYBOOK_HOST=http://localhost:6006

then run pnpm dev to start the local dev server for documentation.

Making a pull request

Commit Convention

Before you create a Pull Request, please check whether your commits comply with the commit conventions used in this repository. When you create a commit, you should follow the convention category(scope or module): message in your commit message while using one of the following categories:

• feat/feature: all changes that introduce completely new code or new features
  • For example: feat(uikit/components), feat(uikit/hooks)
• fix: changes that fix a bug (ideally you will additionally reference an issue if present)
• refactor: any code related change that is not a fix nor a feature
• chore: all changes to the repository that do not fit into any of the above categories

Pull Request

Once you’ve committed your message. You can do your PR

1. Make a changeset

pnpm changeset

2. Follow the changeset interactive prompts, commit your change

git commit -m 'feat(uikit): your message'

3. Push the changes, request a PR. Waiting for the review and merged with the master

Release Process

Each pull request that includes user-facing changes or API modifications should include a changeset:

1. Generate a changeset file:

pnpm changeset

2. Follow the interactive prompts to:

   • Select the packages that have changed
   • Choose the type of change (major/minor/patch)

3. The changeset summary will be generated automatically from commit history. Commit the generated .changeset/*.md file along with your changes.

The changeset bot will also check your PR and comment if a changeset is missing in your PR. You can also use the link provided by the bot to create a changeset directly through GitHub’s UI.

Then the release process will be handled automatically:

• When PRs with changesets are merged, a Release PR that will bump the version and update the changelog will be created by the changeset bot.
• Once the Release PR is approved and merged, packages will be published to the registry automatically.

Prerelease

For beta versions, you can use the following command to enter prerelease mode, then follow the instructions just like the normal release process to include a changeset in every PR:

npx changeset pre enter beta

After you are done with your beta changes, you can exit the prerelease mode by running:

npx changeset pre exit

Then run changeset version to version packages with normal versions.

Snapshot release

Snapshot releases are a way to release your changes for testing without impacting real users. They allow you to publish experimental versions based on your current branch.

Triggering via GitHub Actions (Recommended)

The easiest way to create a snapshot release is through GitHub Actions:

1. Go to the Actions tab in the tidbcloud/uikit repository.
2. Find and select the Manual Snapshot Release workflow in the left sidebar.
3. Click the Run workflow dropdown button on the right.
4. Select the branch you want to release from (usually your feature branch).
5. Click the green Run workflow button.

The CI/CD pipeline will then automatically:

• Build the necessary packages.
• Version the packages using a timestamp format (e.g., 0.0.0-20250423031914).
• Publish these packages to npm under the experimental tag.

Once the workflow completes, you can install the snapshot version in other projects using pnpm add @tidbcloud/uikit@experimental or yarn add @tidbcloud/uikit@experimental.

Manual Triggering (Alternative)

Alternatively, you can still create a snapshot release manually. First, create a changeset just like the normal release process:

pnpm changeset

Then, use the snapshot flag to bump the versions:

npx changeset version --snapshot

This will apply the changeset, but instead of using the next semantic version, all versions will be set to 0.0.0-<TIMESTAMP>.

After running the version command, you will need to use the publish command locally to release the packages:

npx changeset publish --tag experimental

Using the --tag experimental flag ensures you do not publish it to the latest tag on npm. This is crucial because omitting the tag would cause users installing with pnpm add @tidbcloud/uikit (or yarn) to get the snapshot version instead of the latest stable release.