# Contributing

Thanks for your interest in contributing to Headless UI! Please take a moment to review this document **before submitting a pull request**.

- [Pull requests](#pull-requests)
- [Monorepo](#monorepo)
- [Installation](#installation)
- [Coding standards](#coding-standards)
- [Running tests](#running-tests)
- [Running playgrounds](#running-playgrounds)
- [Scripts summary](#scripts-summary)

## Pull requests

**Please ask first before starting work on any significant new features.**

It's never a fun experience to have your pull request declined after investing a lot of time and effort into a new feature. To avoid this from happening, we request that contributors create [an issue](https://github.com/tailwindlabs/headlessui/issues) to first discuss any significant new features. This includes things like adding new components, exposing internal information, etc.
Also make sure that you are making changes to both the `React` and `Vue` versions so that we can ensure feature parity.

## Monorepo

The Headless UI repo is a monorepo using `npm` workspaces.

## Installation

You only require a `npm install` in the root directory to install everything you need.

```sh
npm install
```

## Coding standards

We use `prettier` for making sure that the codebase is formatted consistently.
To automatically fix any style violations in your code, you can run:

```sh
npm lint
```

**Note**: Whenever you commit, the lint check will run on all staged files.
**Note**: In CI, we will only check your code, and not write with the formatted files. If you want to just check, then you can either run `npm run lint-check` or `CI=true npm run lint`

## Running tests

You can run the test suite using the following commands:

```sh
npm run test
```

You can also run them for React or Vue individually:

```sh
npm run react test

# or

npm run vue test
```

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

## Running playgrounds

Currently the `React` playground (located in `packages/playground-react`) is a Next.js app that contains some examples which you can find in the `pages` directory. The `Vue` playground (located in `packages/playground-vue`) is a Vite app that contains some examples which you can find in the `src/components` directory.

You can launch them by running:

```sh
npm run react playground

# or

npm run vue playground
```

This will also start the necessary watchers so that you don't have to care about them.

## Scripts summary

Global scripts, and some aliases:

- `npm install`: install all dependencies for all packages
- `npm run clean`: this will call all `npm run {package} clean` commands
- `npm run build`: this will call all `npm run {package} build` commands
- `npm run lint`: this will `lint` all packages
- `npm run test`: this will `test` all packages
  - `npm run test`: run all jest tests
  - `npm run test --watch`: run all jest tests in interactive mode
  - `npm run test tabs`: run all jest tests filtered by `tabs`
  - `npm run test tabs --watch`: run all jest tests in interactive mode filtered by `tabs`

Scripts per package:

- `npm run react`: Prefix to run anything in the `@headlessui/react` package
  - `npm run react test`: run all jest tests
  - `npm run react test --watch`: run all jest tests in interactive mode
  - `npm run react test tabs`: run all jest tests filtered by `tabs`
  - `npm run react test tabs --watch`: run all jest tests in interactive mode filtered by `tabs`
  - `npm run react build`: build the final artefacts
  - `npm run react lint`: validate and fix the react codebase using prettier
  - `npm run react watch`: start a watcher for the react esm build
    - **Note**: this will be executed for you when using the `npm run react playground`
    - **Note**: this is not required for jest. You will probably never need this
  - `npm run react playground`: (alias) start a development server in the `playground-react` package
    - **Note**: this will also run `npm run react watch` for you, which means that you only need to execute `npm run react playground`
  - `npm run react clean`: this will remove `dist` files
- `npm run vue`: Prefix to run anything in the `@headlessui/vue` package
  - `npm run vue test`: run all jest tests
  - `npm run vue test --watch`: run all jest tests in interactive mode
  - `npm run vue test tabs`: run all jest tests filtered by `tabs`
  - `npm run vue test tabs --watch`: run all jest tests in interactive mode filtered by `tabs`
  - `npm run vue build`: build the final artefacts
  - `npm run vue lint`: validate and fix the vue codebase using prettier
  - `npm run vue watch`: start a watcher for the vue esm build
    - **Note**: this will be executed for you when using the `npm run vue playground`
    - **Note**: this is not required for jest. You will probably never need this
  - `npm run vue playground`: (alias) start a development server in the `playground-vue` package
    - **Note**: this will also run `npm run vue watch` for you, which means that you only need to execute `npm run react playground`
  - `npm run vue clean`: this will remove `dist` files