Packages Overview

Packages Overview

Cosella’s monorepo contains 13 shared packages that provide common functionality across all applications.

Package List

Package	Description	Dependencies
@cosella/ui	React component library (25+ components)	tokens
@cosella/tokens	Design tokens (CSS + JS)	-
@cosella/domain	Zod schemas + TypeScript types	-
@cosella/api-client	Generated OpenAPI types + TanStack Query hooks	domain
@cosella/realtime	Typed WebSocket client with reconnect	domain
@cosella/auth	Auth provider, session store	domain
@cosella/permissions	Capability-based permission helpers	domain, auth
@cosella/testing	MSW server + handlers + fixtures	domain
@cosella/observability	Error boundaries, Sentry, redaction	ui, domain
@cosella/app-shell	AppShell layout, Sidebar, TopBar	auth, tokens, ui
@cosella/forms	React Hook Form + Zod integration	ui
@cosella/audio-capture	Audio capture (Web + Electron)	domain
@cosella/audio-engine	Audio pipeline, VAD, Opus encoding	domain

Usage Patterns

UI Components

import { Button, Card, Input, Alert, Modal, DataTable } from '@cosella/ui';

function MyForm() {
  return (
    <Card>
      <Alert variant="info" title="Welcome" />
      <Input placeholder="Enter email" />
      <Button variant="primary">Submit</Button>
    </Card>
  );
}

Design Tokens

/* In your CSS file */
@import "tailwindcss";
@import "@cosella/tokens/theme.css";
@import "@cosella/tokens/components.css";

/* Use tokens in Tailwind */
.my-component {
  background-color: var(--color-brand-500);
  color: var(--color-text-primary);
  border-radius: var(--radius-lg);
  padding: 1rem;
}

Domain Types

import { UserSchema, type User } from '@cosella/domain';

// Validate API responses
const user = UserSchema.parse(apiResponse);

// Use in TypeScript
function greet(user: User) {
  return `Hello, ${user.name}!`;
}

API Client

import { useQuery, useMutation } from '@tanstack/react-query';
import { api } from '@cosella/api-client';
import { callKeys } from '@cosella/api-client';

// Fetch data with centralized query keys
const { data: calls } = useQuery({
  queryKey: callKeys.list(filters),
  queryFn: () => api.calls.list(filters),
});

// Mutate data
const createCall = useMutation({
  mutationFn: (data) => api.calls.create(data),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: callKeys.lists() });
  },
});

Permissions

import { useCapability } from '@cosella/permissions';

function AdminPanel() {
  const canManage = useCapability('admin:manage');
  if (!canManage) return null;
  return <div>Admin content</div>;
}

App Shell

import { AppShell, Sidebar, TopBar } from '@cosella/app-shell';

function App() {
  return (
    <AppShell>
      <Sidebar />
      <TopBar />
      <main>{/* Page content */}</main>
    </AppShell>
  );
}

Development

Adding a New Package

Use the Plop generator:

pnpm gen package

This creates:

• packages/<name>/package.json
• packages/<name>/tsconfig.json
• packages/<name>/src/index.ts

Adding a New Component

pnpm gen component

This creates:

• packages/ui/src/<kebab-name>/<Name>.tsx
• packages/ui/src/<kebab-name>/<Name>.test.tsx
• Export added to packages/ui/src/index.ts

Dependency Rules

Hard constraints (enforced by ESLint):

1. Apps may depend on packages — never the reverse
2. Packages may not depend on sibling apps
3. packages/ui → packages/tokens only

Publishing

Packages are published to npm as @cosella/* scoped packages:

# Build all packages
pnpm build

# Publish (requires npm auth)
pnpm publish --access public

Next Steps

• UI Components - Component library reference
• Design Tokens - Token system
• Architecture Decisions - Technical decisions
• Vibecoder UI Guide - Safe UI-only contributions