Skip to content

Commit

Permalink
docs: update README with comprehensive design system documentation
Browse files Browse the repository at this point in the history 
This commit provides a comprehensive update to the project's README files, focusing on:

- Restructuring the main README with a detailed project overview
- Adding comprehensive documentation for the UI component library
- Updating package structure and export configurations
- Enhancing development and contribution guidelines
- Providing clear component organization and usage instructions
- Documenting project goals, technologies, and development workflow
  • Loading branch information
@aryasaatvik
aryasaatvik committed Feb 23, 2025
1 parent 0972dab commit e8b6cfa
Show file tree
Hide file tree
Showing 4 changed files with 487 additions and 208 deletions.
281 changes: 141 additions & 140 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,129 +1,141 @@
# Turborepo Design System Starter
# Arya Design System Monorepo

This is a community-maintained example. If you experience a problem, please submit a pull request with a fix. GitHub Issues will be closed.
A modern, accessible React component library and documentation built by Arya Labs, powered by Turborepo, shadcn/ui, and Storybook.

This guide explains how to use a React design system starter powered by:
## Overview

- 🏎 [Turborepo](https://turbo.build/repo) — High-performance build system for Monorepos
- 🚀 [React](https://reactjs.org/) — JavaScript library for user interfaces
- 🛠 [Rollup](https://rollupjs.org/) - Bundler for Component Library
- 📖 [Storybook](https://storybook.js.org/) — UI component environment powered by Vite
This monorepo contains our design system implementation and documentation, powered by:

As well as a few others tools preconfigured:
- 🏎 [Turborepo](https://turbo.build/repo) — High-performance monorepo build system
- 🎨 [shadcn/ui](https://ui.shadcn.com/) — Re-usable components built using Radix UI and Tailwind CSS
- 📖 [Storybook](https://storybook.js.org/) — UI component documentation and testing
- ⚛️ [React](https://reactjs.org/) — UI component library
- 🛠 [TypeScript](https://www.typescriptlang.org/) — Type safety
- 📦 [Changesets](https://github.com/changesets/changesets) — Version management and changelogs

- [TypeScript](https://www.typescriptlang.org/) for static type checking
- [ESLint](https://eslint.org/) for code linting
- [Prettier](https://prettier.io) for code formatting
- [Changesets](https://github.com/changesets/changesets) for managing versioning and changelogs
- [GitHub Actions](https://github.com/changesets/action) for fully automated package publishing
## Project Structure

## Using this example

Run the following command:

```sh
npx create-turbo@latest -e design-system
```
.
├── apps/
│ └── docs/ # Storybook documentation site
│ ├── stories/ # Component stories
│ └── .storybook/ # Storybook configuration
│
├── packages/
│ ├── ui/ # Core React components
│ │ ├── src/
│ │ │ ├── components/
│ │ │ │ ├── primitives/ # Base shadcn/Radix components
│ │ │ │ ├── composed/ # Higher-order components
│ │ │ │ └── patterns/ # Common UI patterns/layouts
│ │ │ ├── hooks/ # Shared hooks
│ │ │ ├── utils/ # Utility functions
│ │ │ ├── styles/ # Global styles
│ │ │ └── types/ # Shared TypeScript types
│ │ └── dist/ # Compiled output
│ │
│ ├── typescript-config/ # Shared TypeScript configs
│ └── eslint-config/ # Shared ESLint configs
```

### Useful Commands

- `pnpm build` - Build all packages, including the Storybook site
- `pnpm dev` - Run all packages locally and preview with Storybook
- `pnpm lint` - Lint all packages
- `pnpm changeset` - Generate a changeset
- `pnpm clean` - Clean up all `node_modules` and `dist` folders (runs each package's clean script)

## Turborepo

[Turborepo](https://turbo.build/repo) is a high-performance build system for JavaScript and TypeScript codebases. It was designed after the workflows used by massive software engineering organizations to ship code at scale. Turborepo abstracts the complex configuration needed for monorepos and provides fast, incremental builds with zero-configuration remote caching.
Each package and app is 100% [TypeScript](https://www.typescriptlang.org/). We use pnpm workspaces to manage the monorepo, which enables dependency hoisting for better performance and smaller node_modules.

Using Turborepo simplifies managing your design system monorepo, as you can have a single lint, build, test, and release process for all packages. [Learn more](https://vercel.com/blog/monorepos-are-changing-how-teams-build-software) about how monorepos improve your development workflow.
## Component Organization

## Apps & Packages
Our UI library is organized into three main categories:

This Turborepo includes the following packages and applications:
1. **Primitives** (`/primitives`)
- Base components built on shadcn/ui and Radix UI
- Fully accessible and customizable
- Examples: Button, Input, Dialog, Select

- `apps/docs`: Component documentation site with Storybook
- `packages/ui`: Core React components
- `packages/typescript-config`: Shared `tsconfig.json`s used throughout the Turborepo
- `packages/eslint-config`: ESLint preset
2. **Composed Components** (`/composed`)
- Higher-order components combining multiple primitives
- Pre-configured for common use cases
- Examples: SearchInput, FormField, DataTable

Each package and app is 100% [TypeScript](https://www.typescriptlang.org/). Workspaces enables us to "hoist" dependencies that are shared between packages to the root `package.json`. This means smaller `node_modules` folders and a better local dev experience. To install a dependency for the entire monorepo, use the `-w` workspaces flag with `pnpm add`.
3. **UI Patterns** (`/patterns`)
- Full-featured layout patterns and templates
- Reusable UI solutions for common scenarios
- Examples: AuthForm, DashboardLayout, SettingsPage

This example sets up your `.gitignore` to exclude all generated files, other folders like `node_modules` used to store your dependencies.
## Quick Start

### Compilation
### Prerequisites

To make the ui library code work across all browsers, we need to compile the raw TypeScript and React code to plain JavaScript. We can accomplish this with `tsup`, which uses `esbuild` to greatly improve performance.
- Node.js (v22.0.0 or higher)
- pnpm (recommended package manager)

Running `pnpm build` from the root of the Turborepo will run the `build` command defined in each package's `package.json` file. Turborepo runs each `build` in parallel and caches & hashes the output to speed up future builds.
### Development

For `@arya.sh/ui`, the `build` command is equivalent to the following:
1. Install dependencies:
```sh
pnpm install
```

```bash
tsup src/*.tsx --format esm,cjs --dts --external react
2. Start the development environment:
```sh
pnpm dev
```

`tsup` compiles all of the components in the design system individually, into both ES Modules and CommonJS formats as well as their TypeScript types. The `package.json` for `@arya.sh/ui` then instructs the consumer to select the correct format:
This will:
- Start Storybook at `http://localhost:6006`
- Watch for changes in the UI components

```json:ui/package.json
{
"name": "@arya.sh/ui",
"version": "0.0.0",
"sideEffects": false,
"exports":{
"./button": {
"types": "./src/button.tsx",
"import": "./dist/button.mjs",
"require": "./dist/button.js"
}
}
}
```
### Available Commands

Run `pnpm build` to confirm compilation is working correctly. You should see a folder `ui/dist` which contains the compiled output.
- `pnpm build` - Build all packages and apps
- `pnpm dev` - Start development environment
- `pnpm lint` - Lint all packages
- `pnpm format` - Format all files
- `pnpm clean` - Clean up all `node_modules` and `dist` folders

```bash
ui
└── dist
├── button.d.ts <-- Types
├── button.js <-- CommonJS version
├── button.mjs <-- ES Modules version
└── button.d.mts <-- ES Modules version with Types
```
## Package Management

## Components
### Adding Dependencies

Each file inside of `ui/src` is a component inside our design system. For example:
- Root dependencies: `pnpm add -w <package>`
- Package-specific: `pnpm add <package> --filter <target-package>`

```tsx:ui/src/Button.tsx
import * as React from 'react';
### Component Compilation

export interface ButtonProps {
children: React.ReactNode;
}
Run `pnpm build` to confirm compilation is working correctly. You should see a folder `ui/dist` which contains the compiled output.

export function Button(props: ButtonProps) {
return <button>{props.children}</button>;
}
1. Compiles TypeScript and React code to ESM format
2. Creates TypeScript declaration files
3. Handles external dependencies appropriately

Button.displayName = 'Button';
```

When adding a new file, ensure that its specifier is defined in `package.json` file:
### Package Exports

Components are exported individually for better tree-shaking. The `package.json` for `@arya.sh/ui` specifies exports:

```json:ui/package.json
{
"name": "@arya.sh/ui",
"version": "0.0.0",
"sideEffects": false,
"exports":{
"./button": {
"types": "./src/button.tsx",
"import": "./dist/button.mjs",
"require": "./dist/button.js"
"type": "module",
"exports": {
"./primitives/*": {
"types": "./dist/components/primitives/*.d.ts",
"import": "./dist/components/primitives/*.mjs"
},
"./composed/*": {
"types": "./dist/components/composed/*.d.ts",
"import": "./dist/components/composed/*.mjs"
},
"./patterns/*": {
"types": "./dist/components/patterns/*.d.ts",
"import": "./dist/components/patterns/*.mjs"
},
"./hooks/*": {
"types": "./dist/hooks/*.d.ts",
"import": "./dist/hooks/*.mjs"
},
"./utils": {
"types": "./dist/utils/index.d.ts",
"import": "./dist/utils/index.mjs"
}
// Add new component exports here
}
}
```
Expand All @@ -137,72 +149,61 @@ Storybook provides us with an interactive UI playground for our components. This
- Support using module path aliases like `@arya.sh/ui` for imports
- Write MDX for component documentation pages

For example, here's the included Story for our `Button` component:

```js:apps/docs/stories/button.stories.mdx
import { Button } from '@arya.sh/ui/button';
import { Meta, Story, Preview, Props } from '@storybook/addon-docs/blocks';
### Version Management

<Meta title="Components/Button" component={Button} />
We use [Changesets](https://github.com/changesets/changesets) for version management:

# Button

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec euismod, nisl eget consectetur tempor, nisl nunc egestas nisi, euismod aliquam nisl nunc euismod.

## Props

<Props of={Box} />

## Examples

<Preview>
<Story name="Default">
<Button>Hello</Button>
</Story>
</Preview>
1. Create a changeset:
```sh
pnpm changeset
```

This example includes a few helpful Storybook scripts:
2. Follow the prompts to:
- Select changed packages
- Choose version bump type
- Write change descriptions

- `pnpm dev`: Starts Storybook in dev mode with hot reloading at `localhost:6006`
- `pnpm build`: Builds the Storybook UI and generates the static HTML files
- `pnpm preview-storybook`: Starts a local server to view the generated Storybook UI
3. Commit the generated changeset file

## Versioning & Publishing Packages
### Publishing

This example uses [Changesets](https://github.com/changesets/changesets) to manage versions, create changelogs, and publish to npm. It's preconfigured so you can start publishing packages immediately.
Packages are published automatically through GitHub Actions when changes are merged to main:

You'll need to create an `NPM_TOKEN` and `GITHUB_TOKEN` and add it to your GitHub repository settings to enable access to npm. It's also worth installing the [Changesets bot](https://github.com/apps/changeset-bot) on your repository.
1. Changesets bot creates a PR with version updates
2. PR is reviewed and merged
3. GitHub Action publishes to npm

### Generating the Changelog
## Documentation

To generate your changelog, run `pnpm changeset` locally:
- [UI Components Documentation](apps/docs/README.md)
- [UI Library Documentation](packages/ui/README.md)

1. **Which packages would you like to include?** – This shows which packages and changed and which have remained the same. By default, no packages are included. Press `space` to select the packages you want to include in the `changeset`.
1. **Which packages should have a major bump?** – Press `space` to select the packages you want to bump versions for.
1. If doing the first major version, confirm you want to release.
1. Write a summary for the changes.
1. Confirm the changeset looks as expected.
1. A new Markdown file will be created in the `changeset` folder with the summary and a list of the packages included.
## Contributing

### Releasing
1. Fork the repository
2. Create a new branch
3. Make your changes
4. Create a changeset (`pnpm changeset`)
5. Submit a pull request

When you push your code to GitHub, the [GitHub Action](https://github.com/changesets/action) will run the `release` script defined in the root `package.json`:
### Development Workflow

```bash
turbo run build --filter=docs^... && changeset publish
1. Start development server:
```sh
pnpm dev
```

Turborepo runs the `build` script for all publishable packages (excluding docs) and publishes the packages to npm. By default, this example includes `acme` as the npm organization. To change this, do the following:
2. Make changes to components in `packages/ui/src`
3. View changes in Storybook
4. Add/update stories in `apps/docs/stories`
5. Create a changeset for your changes

- Rename folders in `packages/*` to replace `acme` with your desired scope
- Search and replace `acme` with your desired scope
- Re-run `pnpm install`
### Code Style

To publish packages to a private npm organization scope, **remove** the following from each of the `package.json`'s
- ESLint and Prettier are configured
- Run `pnpm lint` to check for issues
- Run `pnpm format` to format code

```diff
- "publishConfig": {
- "access": "public"
- },
```
## License

MIT © [Arya Labs]
Loading

0 comments on commit e8b6cfa

Please sign in to comment.