Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
278 lines (207 loc) · 6.43 KB

CONTRIBUTING.md

File metadata and controls

278 lines (207 loc) · 6.43 KB
Raw

Contributing to Care UI

Thank you for your interest in contributing to Care UI! This guide will help you add or modify components.

Quick Start

Care UI uses a structured workflow to maintain component quality and registry compatibility.

Development Requirements

Local Development

  • Node.js: 22.16.0 (specified in .nvmrc)
  • pnpm: 10.11.1 (specified in package.json)

Install dependencies:

pnpm install

Cloudflare Pages Deployment

This project deploys to Cloudflare Pages. The build configuration requires:

  1. Node.js version: Automatically detected from .nvmrc file (22.16.0)
  2. pnpm version: Set the environment variable in Cloudflare Pages dashboard: 
    PNPM_VERSION=10.11.1

Build Settings (Cloudflare Pages Dashboard):

  • Build command: pnpm run build
  • Build output directory: dist
  • Root directory: / (project root)

Configuration Files:

  • .nvmrc: Specifies Node.js version (22.16.0)
  • wrangler.toml: Configures Cloudflare Pages deployment with static assets from dist directory

Note: The .nvmrc file is used instead of .tool-versions because Cloudflare Pages doesn't reliably support asdf's .tool-versions format. For pnpm, you must set the PNPM_VERSION environment variable in the Cloudflare Pages dashboard under Settings → Environment Variables.

Adding a New Component

1. Create Component File

Create your component in src/components/ui/:

// src/components/ui/my-component.tsx
/**
 * @name my-component
 * @description A brief description of what it does
 * @dependencies package-name-if-any
 * @type registry:ui
 */
import { cn } from "@/lib/utils"

export function MyComponent({
  className,
  ...props
}: React.ComponentProps<"div">) {
  return (
    <div
      className={cn("base-styles", className)}
      {...props}
    />
  )
}

2. Create Documentation

Add documentation in src/lib/registry/:

// src/lib/registry/my-component.tsx
import React from 'react'
import { type ComponentDoc } from '@/lib/types'
import { MyComponent } from '@/components/ui/my-component'

export const myComponentDoc: ComponentDoc = {
  id: 'my-component',
  name: 'MyComponent',
  description: 'Description of your component',
  preview: {
    component: <MyComponent>Preview</MyComponent>,
    code: `<MyComponent>Example</MyComponent>`
  },
  examples: [
    {
      name: 'Basic Usage',
      description: 'Simple example',
      preview: <MyComponent />,
      code: `<MyComponent />`
    }
  ],
  props: [
    {
      name: 'className',
      type: 'string',
      description: 'Additional CSS classes'
    }
  ]
}

3. Export from Registry

Update src/lib/registry/index.ts:

export { myComponentDoc } from './my-component'

// Add to componentLoaders
const componentLoaders = {
  // ... existing components
  'my-component': () => import('./my-component').then(m => m.myComponentDoc),
}

4. Generate Registry Files

# Generate shadcn-compatible JSON files
npx tsx scripts/generate-registry.ts

# Copy to public directory
cp -r registry/care-ui public/registry/

5. Test Locally

# Start dev server
pnpm dev

# Visit http://localhost:5173
# Navigate to your component in the sidebar
# Verify preview, code, examples, and props display correctly

6. Commit and Deploy

git add .
git commit -m "Add my-component"
git push

Modifying Existing Components

When updating components, follow these steps:

# 1. Edit component source
# src/components/ui/button.tsx

# 2. Update documentation (if needed)
# src/lib/registry/button.tsx

# 3. Regenerate registry
npx tsx scripts/generate-registry.ts && \
cp -r registry/care-ui public/registry/

# 4. Test changes
pnpm dev

# 5. Commit and deploy
git add . && \
git commit -m "Update button component" && \
git push

Quick Reference Commands

One-liner for quick updates:

npx tsx scripts/generate-registry.ts && \
cp -r registry/care-ui public/registry/ && \
git add . && \
git commit -m "Update components" && \
git push

Verify the Registry Is in Sync

The generated JSON under public/registry/care-ui/** must always match the component source. After editing a component, run pnpm build:registry and commit the regenerated files. To confirm there is no drift:

pnpm registry:check

This regenerates the registry and fails (exit 1) if any committed JSON differs from the current source — meaning someone changed a component without running pnpm build:registry. The fix is to run pnpm build:registry and commit the updated files. Run pnpm registry:check before opening a PR.

File Structure

Files You'll Touch

✅ Always edit:

  • src/components/ui/[component].tsx - Component source code
  • src/lib/registry/[component].tsx - Component documentation
  • src/lib/registry/index.ts - Registry exports

❌ Never manually edit:

  • registry/care-ui/**/*.json - Auto-generated by script
  • public/registry/care-ui/**/*.json - Copied from registry/

Best Practices

Component Code

✅ DO:

// Use semantic HTML
<button type="button" {...props}>Click me</button>

// Include proper TypeScript types
interface MyComponentProps extends React.HTMLAttributes<HTMLDivElement> {
  variant?: 'default' | 'outline'
}

// Support className merging
className={cn("base-classes", className)}

// Add accessibility attributes
<button aria-label="Close" aria-pressed={isPressed}>

❌ DON'T:

// Hardcode styles without className support
<div style={{ color: 'red' }}>Bad</div>

// Forget to export from registry index
// Always add to src/lib/registry/index.ts

Documentation

  • Include clear descriptions
  • Provide multiple examples
  • Document all props with types
  • Add accessibility notes when relevant
  • Show common use cases

Accessibility

All components should:

  • Support keyboard navigation
  • Include proper ARIA attributes
  • Work with screen readers
  • Meet WCAG AA color contrast standards
  • Provide focus indicators

Installation for Users

Once deployed, users can install components:

# Install via shadcn CLI
npx shadcn@latest add https://careui.ohc.network/registry/care-ui/my-component/my-component.json

Components will be installed to components/careui/ in the user's project:

import { MyComponent } from "@/components/careui/my-component"

Questions?

Check the Contributing page in the documentation for detailed examples and guidance.