Ruma UI

A modern, production-ready React UI component library and ecosystem
built with TypeScript, Tailwind CSS v4, and enterprise CI/CD.

Documentation · Storybook · npm · Changelog

---

Packages

This is an Nx-managed monorepo. It contains two published packages:

Package	Version	Description
@ruma-kit/ui		Pre-built, tree-shakeable React component library (49 components)
@ruma-kit/cli		CLI to initialise and add components to your project

Which should I use?

Approach	Package	Best for
Import from npm	@ruma-kit/ui	Quick integration, auto-updates, minimal setup
Copy into project	@ruma-kit/cli	Full control, customisation, shadcn-style workflow

Both approaches can be used together.

---

Quick Start

Option A — Import from npm

npm install @ruma-kit/ui

import { Button } from "@ruma-kit/ui";
import "@ruma-kit/ui/ui.css";

export default function App() {
  return <Button size="lg">Hello Ruma UI</Button>;
}

Option B — Add components via CLI

npx @ruma-kit/cli init
npx @ruma-kit/cli add button modal toast

---

Monorepo Structure

ruma-ui/ui
├── ui/                     # @ruma-kit/ui — main component library
│   ├── src/
│   │   ├── components/     # 49 React components
│   │   ├── lib/            # Shared utilities (cn, etc.)
│   │   ├── styles/         # Global CSS & design tokens
│   │   └── registry/       # Component registry definitions
│   └── .storybook/         # Storybook configuration
│
├── packages/
│   └── cli/                # @ruma-kit/cli — CLI tool
│       └── src/
│           ├── commands/   # init.ts, add.ts
│           └── index.ts
│
├── www/                    # Documentation website
├── scripts/                # Build & registry generation scripts
│
├── .github/
│   └── workflows/
│       ├── ci.yml               # Lint, typecheck, test, build
│       ├── release.yml          # Semantic release (alpha/beta/rc/stable)
│       ├── branch-merge.yml     # Controlled branch promotion
│       ├── deploy-storybook-*.yml
│       ├── codeql.yml
│       ├── changeset-version.yml
│       └── dependabot-auto-merge.yml
│
├── nx.json                 # Nx workspace configuration
├── pnpm-workspace.yaml     # pnpm workspace definition
└── .releaserc.js           # semantic-release configuration

---

Development Setup

Prerequisites

Tool	Version
Node.js	≥ 18 (.nvmrc provided — use nvm use)
pnpm	10.18.1 (enforced via packageManager field)

Getting Started

# 1. Clone
git clone https://github.com/ruma-ui/ui.git
cd ui

# 2. Install all workspace dependencies
pnpm install

# 3. Start development
pnpm storybook      # Component dev environment  →  http://localhost:6006
pnpm dev:website    # Documentation website     →  http://localhost:3001

Available Scripts

Script	Description
pnpm dev	Start all dev servers in parallel
pnpm build	Build all packages
pnpm build:production	Production build (sets NODE_ENV=production)
pnpm test	Run all unit tests
pnpm test:watch	Tests in watch mode
pnpm test:coverage	Tests with coverage report
pnpm lint	Run ESLint across the workspace
pnpm lint:fix	Auto-fix lint issues
pnpm typecheck	Run TypeScript type-checking
pnpm format	Format all files with Prettier
pnpm format:check	Check formatting without writing
pnpm storybook	Start Storybook dev server
pnpm validate	Full pipeline: lint + typecheck + test + build
pnpm size	Check bundle size limits
pnpm changeset	Create a new changeset entry
pnpm clean	Reset Nx cache and remove dist/

---

Branch Strategy & Release Process

This project uses a promotion-based branch model with fully automated releases via semantic-release.

Branches

Branch	Channel	npm tag	Purpose
dev	—	—	Active development, all PRs merge here
alpha	Pre-release	alpha	Early testing builds
beta	Pre-release	beta	Feature-complete pre-release
rc	Pre-release	rc	Release candidate — no new features
main	Stable	latest	Production releases

Release Flow

dev  →  alpha  →  beta  →  rc  →  main
         ↓          ↓        ↓       ↓
    1.0.0-alpha  1.0.0-beta 1.0.0-rc  1.0.0

• Prereleases (alpha, beta) trigger automatically on push
• Stable (rc, main) use the changesets/action workflow with a PR-based review gate
• Branch promotions are performed via the Branch Merge Pipeline (workflow_dispatch)

Commit Convention

Releases are version-bumped automatically based on Conventional Commits:

Commit prefix	Release type	Example
feat:	minor	feat: add Resizable component
fix:	patch	fix: modal close on ESC
docs:	patch	docs: update Button examples
refactor:, perf:, style:, test:, build:, ci:	patch	—
chore:	no release	chore: update deps
feat!: / BREAKING CHANGE:	major	—

See COMMIT_GUIDE.md for full commit message guidelines.

---

Contributing

We welcome all contributions — bug fixes, new components, documentation improvements, and more.

Please read our CONTRIBUTING.md before opening a pull request.

Quick Contribution Workflow

# 1. Fork and clone
git clone https://github.com/<your-username>/ui.git
cd ui && pnpm install

# 2. Create a branch off dev
git checkout dev
git checkout -b feat/my-improvement

# 3. Make changes, then validate
pnpm validate

# 4. Commit with conventional format
git commit -m "feat: add amazing improvement"

# 5. Push and open a PR targeting dev
git push origin feat/my-improvement

Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

---

Security

Please do not report security vulnerabilities through public GitHub issues. See SECURITY.md for our responsible disclosure policy.

---

License

MIT © Ruma UI