Contributing

January 3, 2024 ยท View on GitHub

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

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 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.

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:

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:

npm run test

You can also run them for React or Vue individually:

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:

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