|
3 | 3 | Welcome to Open UI Kit development! This guide will help you set up your local development environment and understand our development workflow. |
4 | 4 |
|
5 | 5 | - [🛠️ Repository Setup](#%EF%B8%8F-repository-setup) |
| 6 | +- [📁 Project Structure](#-project-structure) |
6 | 7 | - [🎨 Style and Linting](#-style-and-linting) |
7 | 8 | - [👾 Development & 📚 Documentation](#-development-documentation) |
8 | 9 | - [🗂️ Testing](#%EF%B8%8F-testing) |
@@ -33,7 +34,43 @@ nvm install |
33 | 34 | yarn install |
34 | 35 | ``` |
35 | 36 |
|
36 | | -## 📦 Package Structure |
| 37 | +## 📁 Project Structure |
| 38 | + |
| 39 | +This monorepo is organized as follows: |
| 40 | + |
| 41 | +``` |
| 42 | +open-ui-kit/ |
| 43 | +├── .github/ # GitHub templates and workflows |
| 44 | +│ ├── ISSUE_TEMPLATE/ # Issue templates (bug reports, feature requests, docs) |
| 45 | +│ ├── workflows/ # CI/CD GitHub Actions workflows |
| 46 | +│ └── dependabot.yml # Automated dependency updates |
| 47 | +├── .husky/ # Git hooks for code quality enforcement |
| 48 | +├── .vscode/ # VSCode workspace settings (optional) |
| 49 | +├── docs/ # Additional project documentation |
| 50 | +├── packages/ |
| 51 | +│ └── open-ui-kit/ # 📦 @open-ui-kit/core - Main component library |
| 52 | +│ ├── src/ # Source code for components, themes, utilities |
| 53 | +│ ├── stories/ # Storybook stories for documentation |
| 54 | +│ └── tests/ # Unit and integration tests |
| 55 | +├── playground/ |
| 56 | +│ └── vite-ts/ # 🎮 Development playground with Vite + TypeScript |
| 57 | +├── scripts/ # Build scripts and automation tools |
| 58 | +├── package.json # Root workspace configuration |
| 59 | +├── turbo.json # Turborepo build system configuration |
| 60 | +├── yarn.lock # Dependency lock file |
| 61 | +├── DEVELOPMENT.md # This file - development guidelines |
| 62 | +├── CONTRIBUTING.md # Contribution guidelines and processes |
| 63 | +└── README.md # Main project overview and setup |
| 64 | +``` |
| 65 | + |
| 66 | +### Key Directories |
| 67 | + |
| 68 | +- **`packages/open-ui-kit/`** - The core component library where most development happens |
| 69 | +- **`playground/vite-ts/`** - Interactive development environment for testing components |
| 70 | +- **`.github/`** - CI/CD workflows, issue templates, and GitHub configuration |
| 71 | +- **`scripts/`** - Build and maintenance automation |
| 72 | + |
| 73 | +### Main Packages |
37 | 74 |
|
38 | 75 | This monorepo contains the following main packages: |
39 | 76 |
|
@@ -76,7 +113,7 @@ cd open-ui-kit # Move into the cloned repository |
76 | 113 | yarn install && yarn run build && yarn run storybook # Install & build deps and start Storybook |
77 | 114 | ``` |
78 | 115 |
|
79 | | -The project's main branch Storybook documentation is hosted on [our Storybook instance](https://main--67e2c28f188630b706cee923.chromatic.com). |
| 116 | +The project's main branch Storybook documentation is hosted on [our Storybook instance](https://main--68cc22452afe30d90e4ca977.chromatic.com). |
80 | 117 |
|
81 | 118 | ## 🗂️ Testing |
82 | 119 |
|
@@ -210,3 +247,93 @@ Releases are handled automatically through semantic-release when changes are mer |
210 | 247 | }, |
211 | 248 | } |
212 | 249 | ``` |
| 250 | + |
| 251 | +3. **Creating New Components** - Follow the established file structure pattern: |
| 252 | + |
| 253 | + When creating a new component, follow the structure used by existing components like `ActivityTimeline`. Each component should have its own directory with organized subfolders: |
| 254 | + |
| 255 | + ``` |
| 256 | + packages/open-ui-kit/src/components/[component-name]/ |
| 257 | + ├── components/ |
| 258 | + │ ├── [ComponentName].tsx # Main component implementation |
| 259 | + │ └── [SubComponent].tsx # Sub-components (if needed) |
| 260 | + ├── types/ |
| 261 | + │ ├── [ComponentName].types.ts # Main component type definitions |
| 262 | + │ └── [SubComponent].types.ts # Sub-component types (if needed) |
| 263 | + ├── styles/ |
| 264 | + │ └── [component-name].styles.ts # Component-specific styles |
| 265 | + ├── utils/ |
| 266 | + │ └── [component-name].utils.ts # Component-specific utilities |
| 267 | + ├── stories/ |
| 268 | + │ └── [ComponentName].stories.tsx # Storybook documentation |
| 269 | + ├── __tests__/ |
| 270 | + │ └── [ComponentName].test.tsx # Unit tests |
| 271 | + └── index.ts # Main export file |
| 272 | + ``` |
| 273 | + |
| 274 | + **Required files for a new component:** |
| 275 | + |
| 276 | + - **`index.ts`** - Export the component and its types |
| 277 | + ```tsx |
| 278 | + export { ComponentName } from './components/ComponentName'; |
| 279 | + export type { ComponentNameProps } from './types/ComponentName.types'; |
| 280 | + ``` |
| 281 | + |
| 282 | + - **`components/[ComponentName].tsx`** - Main component implementation |
| 283 | + ```tsx |
| 284 | + import React from 'react'; |
| 285 | + import { ComponentNameProps } from '../types/ComponentName.types'; |
| 286 | + |
| 287 | + export const ComponentName: React.FC<ComponentNameProps> = ({ ...props }) => { |
| 288 | + // Component implementation |
| 289 | + }; |
| 290 | + ``` |
| 291 | + |
| 292 | + - **`types/[ComponentName].types.ts`** - Type definitions |
| 293 | + ```tsx |
| 294 | + export interface ComponentNameProps { |
| 295 | + // Component prop types |
| 296 | + } |
| 297 | + ``` |
| 298 | + |
| 299 | + - **`__tests__/[ComponentName].test.tsx`** - Unit tests |
| 300 | + ```tsx |
| 301 | + import { render, screen } from '@testing-library/react'; |
| 302 | + import { ComponentName } from '../components/ComponentName'; |
| 303 | + |
| 304 | + describe('ComponentName', () => { |
| 305 | + it('renders correctly', () => { |
| 306 | + // Test implementation |
| 307 | + }); |
| 308 | + }); |
| 309 | + ``` |
| 310 | + |
| 311 | + - **`stories/[ComponentName].stories.tsx`** - Storybook documentation |
| 312 | + ```tsx |
| 313 | + import type { Meta, StoryObj } from '@storybook/react'; |
| 314 | + import { ComponentName } from '../components/ComponentName'; |
| 315 | + |
| 316 | + const meta: Meta<typeof ComponentName> = { |
| 317 | + title: 'Components/ComponentName', |
| 318 | + component: ComponentName, |
| 319 | + }; |
| 320 | + |
| 321 | + export default meta; |
| 322 | + type Story = StoryObj<typeof meta>; |
| 323 | + |
| 324 | + export const Default: Story = { |
| 325 | + args: { |
| 326 | + // Default props |
| 327 | + }, |
| 328 | + }; |
| 329 | + ``` |
| 330 | + |
| 331 | + **Additional requirements:** |
| 332 | + - Export your component from `packages/open-ui-kit/src/components/index.ts` |
| 333 | + - Follow naming conventions: PascalCase for components, kebab-case for directories |
| 334 | + - Include comprehensive JSDoc comments for props and functionality |
| 335 | + - Organize types in the dedicated `types/` folder |
| 336 | + - Add component-specific styles to the `styles/` folder |
| 337 | + - Add component-specific utilities to the `utils/` folder |
| 338 | + - Organize sub-components within the same `components/` folder |
| 339 | + |
0 commit comments