Contributing

​

Before You Start

1. Search existing issues to see if your bug/feature has already been reported
2. Open an issue first for significant changes to discuss the approach
3. Read the code of conduct and follow our style guidelines
4. Ensure tests pass before submitting your PR

​

Getting Started

git clone https://github.com/your-org/kivora.git
cd kivora

pnpm install

pnpm --filter @kivora/react build

pnpm --filter @kivora/react test

​

Project Structure

src/
  components/
    buttons/        # Button, ActionIcon, CloseButton
    inputs/         # Input, Checkbox, RadioGroup, Switch, etc.
    feedback/       # Alert, Notification, Spinner, Skeleton, etc.
    overlays/       # Modal, Drawer, Dialog, Popover, Tooltip, etc.
    navigation/     # Tabs, Breadcrumbs, NavLink, Pagination, etc.
    data-display/   # Badge, Avatar, Card, Accordion, etc.
    layout/         # Container, Flex, Grid, Stack, etc.
    typography/     # Text, Title, Anchor, Code, etc.
    misc/           # Divider, Icon, Box, Paper, etc.
  hooks/
    async/          # useDebounce, useThrottle, useInterval, etc.
    browser/        # useClipboard, useColorScheme, useNetwork, etc.
    dom/            # useClickOutside, useMediaQuery, useEventListener, etc.
    state/          # useCounter, useToggle, useListState, etc.
    ui/             # useDisclosure, useControlled, useToast
    utils/          # useMounted, useForceUpdate, useMergedRef, etc.
  index.ts          # Public barrel export
test/               # Vitest + Testing Library test suites

​

Development Workflow

​

Watch Mode

pnpm --filter @kivora/react dev

​

Running Tests

pnpm --filter @kivora/react test

​

Type Checking

pnpm --filter @kivora/react type-check

​

Adding a New Component

src/components/buttons/MyButton.tsx

import type { MyButtonProps } from '@kivora/core';
import { forwardRef } from 'react';

/**
 * Brief description of what this component does.
 *
 * @example
 * ```tsx
 * <MyButton label="Click me" />
 * ```
 */
export const MyButton = forwardRef<HTMLButtonElement, MyButtonProps>(
  ({ label, onClick, className = '' }, ref) => {
    return (
      <button
        ref={ref}
        onClick={onClick}
        className={['base-classes', className].join(' ')}
      >
        {label}
      </button>
    );
  }
);

MyButton.displayName = 'MyButton';

export * from './buttons/MyButton';

// Already exports from './components'

import { render, screen } from '@testing-library/react';
import { MyButton } from '../src/components/buttons/MyButton';
import { describe, it, expect } from 'vitest';

describe('MyButton', () => {
  it('renders with label', () => {
    render(<MyButton label="Click me" />);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });

  it('calls onClick when clicked', () => {
    const onClick = vi.fn();
    render(<MyButton label="Click" onClick={onClick} />);
    screen.getByText('Click').click();
    expect(onClick).toHaveBeenCalledTimes(1);
  });
});

apps/web/src/app/docs/components/my-button/page.tsx

​

Adding a New Hook

src/hooks/browser/useMyHook.ts

import { useState, useEffect } from 'react';

/**
 * Brief description of what this hook does.
 *
 * @example
 * ```tsx
 * const value = useMyHook();
 * ```
 */
export function useMyHook() {
  const [value, setValue] = useState(null);

  useEffect(() => {
    // Hook logic
  }, []);

  return value;
}

export * from './browser/useMyHook';

import { renderHook } from '@testing-library/react';
import { useMyHook } from '../src/hooks/browser/useMyHook';
import { describe, it, expect } from 'vitest';

describe('useMyHook', () => {
  it('returns expected value', () => {
    const { result } = renderHook(() => useMyHook());
    expect(result.current).toBeDefined();
  });
});

apps/web/src/app/docs/hooks/use-my-hook/page.tsx

​

Branch Naming Conventions

• feat/ — New component or hook
• fix/ — Bug fix
• chore/ — Tooling, dependencies, refactor
• docs/ — Documentation only
• test/ — Tests only

git checkout -b feat/add-tooltip-component
git checkout -b fix/button-disabled-state
git checkout -b docs/update-installation-guide

​

Commit Message Format

feat(button): add fullWidth prop
fix(input): correct focus ring on disabled state
test(modal): add controlled open/close tests
docs(readme): update installation instructions
chore(deps): upgrade react to 19.0.0

type(scope): subject

• type: feat, fix, docs, test, chore, refactor, perf
• scope: Component or hook name (lowercase)
• subject: Brief description in present tense

​

Code Style Guidelines

​

Components

• Use forwardRef for components that render HTML elements
• Add displayName to all components
• Include JSDoc comments with examples
• Use Tailwind utility classes for styling
• Destructure props in the function signature
• Use meaningful default values

​

Hooks

• Prefix all hooks with use
• Return objects for multiple values, not tuples (unless following React conventions)
• Include JSDoc with examples
• Add explicit return types

​

TypeScript

• Enable strict mode
• Use explicit types for function parameters and return values
• Prefer interface over type for prop types
• Use React.ReactNode for children
• Avoid any — use unknown if type is truly unknown

​

Testing Guidelines

• Components: Use @testing-library/react to test rendering and user interactions
• Hooks: Use renderHook from @testing-library/react
• Coverage: Aim for >80% code coverage
• Test file naming: Match the component/hook name (Button.test.tsx, useDisclosure.test.ts)

import { render, screen } from '@testing-library/react';
import { Button } from '../src/components/buttons/Button';
import { describe, it, expect } from 'vitest';

describe('Button', () => {
  it('renders label', () => {
    render(<Button label="Click" />);
    expect(screen.getByText('Click')).toBeInTheDocument();
  });

  it('calls onClick when clicked', () => {
    const onClick = vi.fn();
    render(<Button label="Click" onClick={onClick} />);
    screen.getByText('Click').click();
    expect(onClick).toHaveBeenCalledTimes(1);
  });
});

​

Submitting a Pull Request

git checkout -b feat/my-new-feature

pnpm --filter @kivora/react test
pnpm --filter @kivora/react type-check

git add .
git commit -m "feat(button): add fullWidth prop"

git push origin feat/my-new-feature

​

Pull Request Checklist

• Code follows the style guidelines
• All tests pass (pnpm --filter @kivora/react test)
• TypeScript compiles without errors (pnpm --filter @kivora/react type-check)
• New features include tests
• JSDoc comments added to public APIs
• Documentation updated (if applicable)
• Commit messages follow Conventional Commits format

​

Reporting Issues

1. Search existing issues first at github.com/your-org/kivora/issues
2. Click New Issue and choose the appropriate template:
   • 🐛 Bug report — Wrong behavior, broken styles, TypeScript errors
   • 💡 Feature request — New component, new hook, new prop
   • 📚 Documentation — Missing or incorrect docs

​

Bug Report Template

• @kivora/react version
• React version
• Browser and OS
• Minimal reproduction (StackBlitz or CodeSandbox link preferred)
• Expected vs actual behavior
• Steps to reproduce

​

Code Review Process

1. Automated checks run on every PR (tests, type checking, linting)
2. Code review by at least one maintainer
3. Feedback is provided for any necessary changes
4. Approval and merge once all checks pass

​

Next Steps