Rulary (rulary)

Rulary is an accessible React component library forked from Cloudflare Kumo for building modern web applications. The published package and CLI identifiers remain rulary and kumo for compatibility.

Installation

pnpm add rulary

Peer Dependencies

Rulary requires the following peer dependencies:

pnpm add react react-dom @phosphor-icons/react

Component Documentation

Rulary includes a built-in CLI for quick component reference:

npx rulary ls         # List all components
npx rulary doc Button # Get component documentation
npx rulary docs       # Get all component docs

The CLI reads from ai/component-registry.json (generated from TypeScript types + demo examples).

Usage

Import Components

// Main package import
import { Button, Input, LayerCard } from "rulary";

// Granular imports (recommended for tree-shaking)
import { Button } from "rulary/components/button";

Import Styles

For Tailwind CSS Users

Important: Tailwind CSS v4 does not scan node_modules/ by default. You must add a @source directive so Tailwind can discover the utility classes used by Rulary components. Without this, components may render with missing styles (e.g. Dialogs not centered).

In your main CSS file (e.g. app.css):

@source "../node_modules/rulary/dist/**/*.{js,jsx,ts,tsx}";
@import "rulary/styles/tailwind";
@import "tailwindcss";

Import order matters — rulary/styles must come before @import "tailwindcss" so Rulary's @theme tokens are registered first.

Note: The @source path is relative to your CSS file. Adjust it based on your project structure — e.g. if your CSS is in src/styles/, you may need ../../node_modules/rulary/dist/**/*.{js,jsx,ts,tsx}.

Alternatively, you can use the default style export (rulary/styles) which is equivalent to styles/tailwind.

If you are not using Tailwind CSS, use the standalone build instead (see below) — no @source directive is needed.

For Non-Tailwind Users (Standalone)

import "rulary/styles/standalone";

This imports a fully compiled CSS file with all Tailwind utilities and Rulary styles pre-compiled. No Tailwind configuration needed!

What's included in standalone:

• All Tailwind utility classes used by Rulary components
• Rulary component styles
• Dark mode support (via data-mode="dark" attribute)
• All animations and keyframes
• Responsive utilities

Note: The standalone CSS is minified and optimized, but will be larger than the Tailwind version since it includes all utilities.

Development

For comprehensive contributor documentation, see AGENTS.md.

Creating New Components

Use the scaffolding tool to quickly create new components with all required files and configurations:

# Create a new component
pnpm new-component

# Or use the shorthand
pnpm new

What it creates:

• Component file: src/components/{name}/{name}.tsx
• Index file: src/components/{name}/index.ts
• Test file: src/components/{name}/{name}.test.tsx

What it updates:

• src/index.ts - Adds component export
• vite.config.ts - Adds build entry
• package.json - Adds export configuration

Example:

? Component name: Alert Banner

✅ Component scaffolded successfully!

📁 Files created:
   - src/components/alert-banner/alert-banner.tsx
   - src/components/alert-banner/index.ts
   - src/components/alert-banner/alert-banner.test.tsx

The scaffolding tool handles naming automatically - input any format (spaces, PascalCase, kebab-case) and it will convert appropriately.

Creating New Blocks

Blocks are higher-level components that compose multiple base components to create common page patterns. Use the block scaffolding tool:

# Create a new block
pnpm new-block

What it creates:

• Block file: src/blocks/{name}/{name}.tsx
• Index file: src/blocks/{name}/index.ts
• Test file: src/blocks/{name}/{name}.test.tsx

What it updates:

• src/index.ts - Adds block export
• vite.config.ts - Adds build entry
• package.json - Adds export configuration

Blocks are higher-level components that compose multiple base components. See AGENTS.md for detailed documentation on blocks.

Development Workflows

Option 1: Storybook Development (Recommended)

Rulary uses Storybook as a live development environment for building and testing components in isolation. Storybook provides instant feedback, interactive controls, and serves as living documentation for the component library.

Start Storybook:

# From this directory
pnpm storybook

# Or from workspace root
pnpm --filter rulary storybook

Storybook runs at http://localhost:6006 with hot module replacement enabled.

Why use Storybook:

• Full HMR with React Fast Refresh
• Changes reflect instantly without page reload
• Test all component variations and edge cases interactively
• Auto-generated docs from TypeScript types
• Best for isolated component development
• Test keyboard navigation and screen readers

Story files live alongside components:

• Components: src/components/{name}/{name}.stories.tsx
• Blocks: src/blocks/{name}/{name}.stories.tsx

Storybook documentation includes:

• Writing stories guide
• Development workflow
• Best practices

Option 2: Watch Build Mode

When you need to test components in the actual documentation site or consuming application:

Start watch build:

pnpm dev

This runs Vite in watch mode with optimizations for fast rebuilds:

• ⚡~400ms rebuild time (10x faster than production builds)
• Skips minification in development
• Incremental TypeScript compilation
• Selective file watching (ignores tests and stories)
• Validates components against production build output

Using with documentation site:

Terminal 1 (this directory):

pnpm dev

Terminal 2 (from workspace root or kumo-docs):

cd ../kumo-docs
pnpm dev

When you edit a component:

1. Rulary rebuilds automatically (~400ms)
2. Refresh browser to see changes in docs site
3. Changes are validated against the actual build output

Build modes:

• pnpm dev - Development mode (fast, optimized for iteration)
• pnpm build - Production mode (full optimization, minification, CSS processing)

Testing

The package includes comprehensive import validation tests that ensure all components are properly exported and consumable.

Run tests:

# Watch mode
pnpm test

# Single run
pnpm test:run

# With UI
pnpm test:ui

# With coverage
pnpm test:coverage

What's tested:

• All components importable from main entry: import { Component } from "rulary"
• All components importable via deep imports: import { Component } from "rulary/components/component-name"
• All blocks importable from main entry: import { Block } from "rulary"
• All blocks importable via deep imports: import { Block } from "rulary/blocks/block-name"
• Package.json exports sync with actual components and blocks
• Export paths and formats are correct
• Build configuration consistency

Zero maintenance: Tests automatically discover components and blocks from the filesystem and validate against package.json. When adding new items, tests will fail with exact code snippets to fix configuration.

Beta Releases

Beta releases allow you to test changes before publishing to production. Beta versions are automatically created for pull requests and include the commit hash for identification.

Automated Beta Releases

Beta releases are automatically triggered for pull requests through GitHub Actions (.github/workflows/preview.yml):

Workflow Configuration:

• Workflow: preview.yml
• Triggers: Pull requests with changes to packages/kumo/** or .changeset/**
• Dependencies: Requires changeset to exist for rulary

Process Flow:

1. Validate: Ensures changeset exists for rulary
2. Version: Runs pnpm run version:beta
   • Consumes pending changesets
   • Appends -beta.{commit-hash} to version number
3. Build: Runs pnpm --filter rulary build
4. Publish: Publishes to npm with beta tag
5. Notify: Posts PR comment with installation instructions

Secrets Required:

• NPM_TOKEN: Authentication for npm registry
• GITHUB_TOKEN: For posting PR comments (built-in)

Beta Version Format

Beta versions follow this pattern:

{base-version}-beta.{commit-hash}

For example: 0.1.0-beta.a1b2c3d

Installing Beta Versions

When a beta is published, the PR will include a comment with installation instructions:

# Install the specific beta version
npm install [email protected]

# Or with pnpm
pnpm add [email protected]

Testing Beta Releases

1. Create PR: Submit your changes with a changeset
2. Wait for Beta: The beta job runs automatically after changeset validation passes
3. Install Beta: Use the version from the PR comment
4. Test Changes: Verify functionality in your project
5. Merge: Once tested, merge the PR for production release

Changeset Validation

All pull requests with changes to packages/kumo/ must include a changeset:

# Create a changeset
pnpm changeset

• Select rulary when prompted
• Choose the type of change: patch, minor, or major
• Write a clear description of what changed

The CI will automatically validate that a changeset exists before allowing beta publication.

Production Releases

This package uses Changesets for version management and automated releases.

Creating a Release

1. Check for existing changesets:

   # List any pending changesets
   ls .changeset/*.md 2>/dev/null | grep -v "README\|USAGE" || echo "No pending changesets"

2. Create a changeset for your changes (if necessary):

   pnpm changeset

   • Select rulary from the list
   • Select the type of change: patch, minor, or major
   • Write a clear description of what changed
   • This creates a .changeset/*.md file describing the change

Release Workflow

1. Development: Make changes to components or blocks
2. Changeset: Create changeset describing the changes
3. Review: Submit PR with changes and changeset
4. Beta Test: Test the beta version published to the PR
5. Merge: Merge PR to main branch
6. Release: Run the production release process

Production Release Process

To publish a production release:

# 1. Ensure you're on main branch with latest changes
git checkout main
git pull

# 2. Version all packages (consumes changesets)
pnpm version

# 3. Build all packages
pnpm build:all

# 4. Publish to npm
pnpm release

This will:

• Update package.json with new version
• Generate/update CHANGELOG.md
• Remove consumed changeset files
• Publish to npm registry
• Create git tags

Post-Release

After publishing:

1. Commit version changes:

   git add .
   git commit -m "chore: release rulary@{version}"
   git push

2. Push tags:

   git push --tags

3. Verify publication:

   npm view rulary versions

Semantic Versioning

Follow semantic versioning guidelines:

• Patch (0.0.1): Bug fixes, small component updates, style tweaks
• Minor (0.1.0): New components, new features, backwards-compatible changes
• Major (1.0.0): Breaking changes, removed components, API changes

Release Notes

Changesets automatically generate:

• Updated package.json version
• CHANGELOG.md with release notes
• Git tags for each release

The changelog includes all changeset descriptions, providing clear documentation of what changed in each release.

Troubleshooting

Common Issues

Changeset Validation Failed

If the CI fails with a changeset validation error:

1. Check if changeset exists: Run ls .changeset/*.md to see pending changesets
2. Create changeset: Run pnpm changeset and select rulary
3. Verify changeset targets correct package: Open the changeset file and ensure it includes rulary
4. Commit changeset: Add and commit the changeset file to your branch

Beta Publication Failed

If the beta release job fails:

1. Check build: Ensure pnpm build succeeds locally
2. Check npm token: Verify npm authentication is configured in CI
3. Check version format: Ensure version follows semver format
4. Review CI logs: Check GitHub Actions logs for specific error messages

Import Errors After Release

If consumers report import errors:

1. Verify exports: Check package.json exports match actual files
2. Run tests: Ensure pnpm test:run passes
3. Check build output: Verify dist/ contains expected files
4. Test locally: Use npm link to test package locally before publishing