shadcn__ui/CONTRIBUTING.md

# Contributing

Thanks for your interest in contributing to ui.shadcn.com. We're happy to have you here.

Please take a moment to review this document before submitting your first pull request. We also strongly recommend that you check for open issues and pull requests to see if someone else is working on something similar.

If you need any help, feel free to reach out to [@shadcn](https://twitter.com/shadcn).

## About this repository

This repository is a monorepo.

- We use [pnpm](https://pnpm.io) and [`workspaces`](https://pnpm.io/workspaces) for development.
- We use [Turborepo](https://turbo.build/repo) as our build system.
- We use [changesets](https://github.com/changesets/changesets) for managing releases.

## Structure

This repository is structured as follows:

```
apps
└── v4
    ├── app
    ├── components
    ├── content
    └── registry
        └── new-york-v4
            ├── example
            └── ui
packages
└── shadcn
```

| Path                 | Description                              |
| -------------------- | ---------------------------------------- |
| `apps/v4/app`        | The Next.js application for the website. |
| `apps/v4/components` | The React components for the website.    |
| `apps/v4/content`    | The content for the website.             |
| `apps/v4/registry`   | The registry for the components.         |
| `packages/shadcn`    | The `shadcn` package.                    |

## Development

### Fork this repo

You can fork this repo by clicking the fork button in the top right corner of this page.

### Clone on your local machine

```bash
git clone https://github.com/your-username/ui.git
```

### Navigate to project directory

```bash
cd ui
```

### Create a new Branch

```bash
git checkout -b my-new-branch
```

### Install dependencies

```bash
pnpm install
```

### Run a workspace

You can use the `pnpm --filter=[WORKSPACE]` command to start the development process for a workspace.

#### Examples

1. To run the `ui.shadcn.com` website:

```bash
pnpm --filter=v4 dev
```

> **Fresh clone?** The generated styles are not checked into git. Run
> `pnpm --filter=v4 registry:build --style all` once before starting the dev
> server. If you forget, the dev server will fail fast and tell you exactly
> this.

2. To run the `shadcn` package:

```bash
pnpm --filter=shadcn dev
```

## Running the CLI Locally

To run the CLI locally, you can follow the workflow:

1. Start by running the dev server:

   ```bash
   pnpm dev
   ```

2. In another terminal tab, test the CLI by running:

   ```bash
   pnpm shadcn
   ```

   To test the CLI in a specific app, use a command like:

   ```bash
   pnpm shadcn <init | add | ...> -c ~/Desktop/my-app
   ```

This workflow ensures that you are running the most recent version of the registry and testing the CLI properly in your local environment.

## Documentation

The documentation for this project is located in the `v4` workspace. You can run the documentation locally by running the following command:

```bash
pnpm --filter=v4 dev
```

Documentation is written using [MDX](https://mdxjs.com). You can find the documentation files in the `apps/v4/content/docs` directory.

## Components

We use a registry system for developing components. You can find the source code for the components under `apps/v4/registry`. The components are organized by styles.

```bash
apps
└── v4
    └── registry
        └── new-york-v4
            ├── example
            └── ui
```

When adding or modifying components, please ensure that:

1. You make the changes for every style.
2. You update the documentation.
3. You run `pnpm registry:build` to update the registry.

See [`apps/v4/registry/README.md`](apps/v4/registry/README.md) for how the
registry pipeline is structured and for the faster targeted build modes
(`--style`, `--registry`, `--examples`, `--indexes`) you can use while
iterating locally. Always run the full `pnpm registry:build` before committing.

Note that most generated output is not tracked in git: the installable JSON
under `apps/v4/public/r/styles` and the compiled styles under `apps/v4/styles`
are gitignored and rebuilt on every deploy. Running `registry:build` will not
dirty your working tree with generated files — only changes to the authored
sources (e.g. `registry/bases`) and the tracked indexes are committed.

## Commit Convention

Before you create a Pull Request, please check whether your commits comply with
the commit conventions used in this repository.

When you create a commit we kindly ask you to follow the convention
`category(scope or module): message` in your commit message while using one of
the following categories:

- `feat / feature`: all changes that introduce completely new code or new
  features
- `fix`: changes that fix a bug (ideally you will additionally reference an
  issue if present)
- `refactor`: any code related change that is not a fix nor a feature
- `docs`: changing existing or creating new documentation (i.e. README, docs for
  usage of a lib or cli usage)
- `build`: all changes regarding the build of the software, changes to
  dependencies or the addition of new dependencies
- `test`: all changes regarding tests (adding new tests or changing existing
  ones)
- `ci`: all changes regarding the configuration of continuous integration (i.e.
  github actions, ci system)
- `chore`: all changes to the repository that do not fit into any of the above
  categories

  e.g. `feat(components): add new prop to the avatar component`

If you are interested in the detailed specification you can visit
https://www.conventionalcommits.org/ or check out the
[Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines).

## Requests for new components

If you have a request for a new component, please open a discussion on GitHub. We'll be happy to help you out.

## CLI

The `shadcn` package is a CLI for adding components to your project. You can find the documentation for the CLI [here](https://ui.shadcn.com/docs/cli).

Any changes to the CLI should be made in the `packages/shadcn` directory. If you can, it would be great if you could add tests for your changes.

## Testing

Tests are written using [Vitest](https://vitest.dev). You can run all the tests from the root of the repository.

```bash
pnpm test
```

Please ensure that the tests are passing when submitting a pull request. If you're adding new features, please include tests.