Robin Malfait
a73007388f
* bump Next in playground * convert legacy Link after Next.js bump * update yarn.lock * switch to npm workspaces * move `packages/playground-*` to `playgrounds/*` * use `npm` instead of `yarn` * sync package-lock.json * use node 20 for insiders releases
122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
# 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
|