Project Structure

Repository Overview

The project follows a monorepo structure with multiple packages managed by Turbo:

matrix-ui/
├── apps/
│   └── docs/              # Documentation site (Next.js)
├── packages/
│   ├── components/        # Core UI components
│   ├── utils/             # Utility functions
│   ├── mcp-server/        # MCP server for AI integration
│   ├── cli/               # CLI tool for component installation
│   ├── themes/            # Theme presets and configurations
│   └── tsconfig/          # Shared TypeScript configurations
├── turbo.json             # Turbo configuration
└── package.json           # Root package configuration with npm workspaces

Package Details

@matrix-ui/components

The core component library containing all UI components. Built with React, TypeScript, and Radix UI primitives.

• 21+ accessible components
• Full TypeScript support with exported types
• Tailwind CSS styling with class-variance-authority
• Tree-shakeable exports

@matrix-ui/utils

Utility functions used across the component library:

• debounce - Debounce function execution
• throttle - Throttle function execution
• compose-refs - Compose multiple React refs
• merge-props - Merge component props intelligently

@matrix-ui/mcp-server

Model Context Protocol server for AI-powered development workflows:

• Component discovery and implementation tools
• Theme generation and validation
• HTTP gateway for tool access
• Comprehensive test coverage

@matrix-ui/cli

Command-line interface for scaffolding and component installation:

• Initialize new projects with Matrix UI
• Add individual components to existing projects
• Configure themes and styling

Development Workflow

Scripts

Common development commands from the root directory:

# Install dependencies
npm install

# Build all packages
npm run build

# Run development servers
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

Package Dependencies

Internal package dependencies are managed through the workspace:

// In your app's package.json
{
  "dependencies": {
    "@matrix-ui/components": "workspace:*",
    "@matrix-ui/utils": "workspace:*"
  }
}

Configuration Files

Turbo Configuration

The turbo.json file defines the build pipeline and task dependencies:

• Parallel builds for improved performance
• Intelligent caching for faster subsequent builds
• Task orchestration across packages

TypeScript Configuration

Shared TypeScript configurations in packages/tsconfig:

• base.json - Base configuration for all packages
• nextjs.json - Next.js specific configuration
• react-library.json - React library configuration

Best Practices

• Keep packages focused and single-purpose
• Use workspace protocol for internal dependencies
• Leverage Turbo caching for faster builds
• Follow consistent naming conventions across packages
• Document package-specific configurations in their README files