Conversion UI Library

Features

• 🚀 React Components - Modern, reusable UI components built with React and hooks
• 🎨 Tailwind + shadcn/ui - Fully styled with Tailwind utility classes and Radix primitives
• 📚 Storybook Integration - Interactive component documentation
• 🧩 Modular Components - Composable and reusable across multiple projects
• ⚡ Fast Builds - Optimized library build pipeline
• 🛠️ TypeScript Support - Strong typing and autocompletion
• 🎯 Theming Ready - Easily customize colors, typography, and spacing

Quick Start

Prerequisites

• Node.js (v18 or higher)
• Yarn (v1 or Berry)
• Consumer app: React ^19.2.0 and React DOM ^19.2.0 (peer dependencies)

Installation

# Clone the repository
git clone <repository-url>
cd conversion-ui-library

# Install dependencies
yarn install

# Run Storybook to view and develop components
yarn storybook

# Build the library before using it in another project
yarn build

# Create a local package to use in another project
yarn local:pack

Using the Library in Another Project

1. Install the Library

From the client project root:

# Using yarn pack to test the local library in the consumer project without publishing
yarn add /absolute/path/to/conversion-ui-library/artifacts/conversion-ui-library-<version>.tgz
# Example:
yarn add /home/developer/Desktop/codebase/conversion-ui-library/artifacts/conversion-ui-library-1.0.0.tgz

2. Import Global Styles (Required)

In your client app entry file (main.tsx / index.tsx):

import "conversion-ui-library/styles.css";

This is required because the components rely on Tailwind utility classes (for example gap-1.5) and design tokens (for example bg-soft, text-strong) that are shipped in that stylesheet.

Recommended Workflow

Library Development:
├── yarn storybook      # Run Storybook to view components
├── update components   # Make component changes
├── yarn build          # Build the library
├── yarn pack           # Pack for local testing
└── test in client app  # Test integration in your app

Project Structure

conversion-ui-library/
├── src/
│   ├── components/      # Reusable UI components
│   ├── styles/          # Global and theme styles
│   ├── utils/           # Utility functions
│   ├── hooks/           # Custom React hooks
│   └── index.ts         # Library entry point
├── .storybook/          # Storybook config
├── package.json
├── tsconfig.json
└── README.md

Example Component Usage

import { Button } from "conversion-ui-library";

export default function App() {
  return <Button variant="primary">Click Me</Button>;
}

Dependencies

React (^19.2.0, peer dependency) Tailwind CSS shadcn/ui Radix UI Storybook TypeScript

Troubleshooting

Invalid hook call (e.g. Cannot read properties of null (reading 'useState'))

This almost always means the app ended up with more than one copy of React (or mismatched react / react-dom versions).

• Ensure React + React DOM versions match in the consuming app (React 19 requires React DOM 19).
• Check for duplicate React installs:
  • npm ls react react-dom
  • yarn why react && yarn why react-dom
• If you’re using Vite, add dedupe in the consuming app’s vite.config.ts:

export default defineConfig({
  resolve: {
    dedupe: ["react", "react-dom"],
  },
});

• If you’re consuming the library locally, avoid linking the repo folder directly (it can accidentally resolve react from this library’s own node_modules).
  • Prefer yarn pack and install the generated .tgz, or publish/install from npm.

Scripts

yarn storybook     # Run Storybook
yarn build         # Build the library
yarn local:pack    # Build and pack for local usage (creates .tgz in artifacts/)

Publishing to npm

The library is automatically published to npm when the version in package.json changes on the main branch.

Automatic Publishing Workflow

1. Update the version in package.json:

   # Bump version (patch, minor, or major)
   npm version patch  # 1.0.0 -> 1.0.1
   # or
   npm version minor  # 1.0.0 -> 1.1.0
   # or
   npm version major  # 1.0.0 -> 2.0.0

2. Commit and push to main:

   git add package.json
   git commit -m "Bump version to 1.0.1"
   git push origin main

3. GitHub Actions automatically:

   • ✅ Detects the version change
   • ✅ Builds the package
   • ✅ Creates a git tag (e.g., v1.0.1)
   • ✅ Publishes to npm
   • ✅ Creates a GitHub release

If the version hasn't changed, the workflow skips publishing (no accidental publishes!).

Manual Publishing (Optional)

You can also manually trigger publishing:

• Go to GitHub → Actions → "Build, Publish and Deploy"
• Click "Run workflow"
• Enable "Publish to npm"
• Click "Run workflow"

This will publish even if the version hasn't changed.

Note: Make sure the NPM_TOKEN secret is configured in your GitHub repository settings.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Sharad Wankhade (@sharadwankhade)