# How to contribute

> How to contribute to Tabler: set up the repository, make and test a change, add a changeset and open a pull request.

Guide to contributing to Tabler and setting up for development.

Source: https://docs.tabler.io/ui/getting-started/how-to-contribute

---

Contributions are welcome, from a typo fix to a new component. If you haven't contributed to open source before, the [how to contribute](https://opensource.guide/how-to-contribute/) guide explains the basics.

Not sure where to start? Look for issues labeled [good first issue](https://github.com/tabler/tabler/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - they are small and well-scoped.

## Contribution requirements

When contributing to Tabler, please adhere to the following guidelines:

1. By submitting a contribution, you grant a non-exclusive license to the Tabler project to use your contribution in any context deemed appropriate.
2. If your contribution includes content from other sources, it must be appropriately licensed under an open source license.
3. Contributions must be submitted via GitHub pull requests.
4. Ensure your code works in all supported browsers (refer to our [browser support documentation](/ui/getting-started/browser-support)).

## Installation

Follow these steps to set up Tabler for development:

1. Fork the repository: [Guide to forking](https://docs.github.com/en/get-started/quickstart/fork-a-repo).

2. Clone the repository to your local machine:

   ```bash
   git clone https://github.com/YOUR_USERNAME/tabler.git
   ```

3. Create a new branch for your changes:

   ```bash
   # Use the project branch naming convention, e.g.:
   git checkout -b fix/markdown-table-overflow
	```

## Development

You can skip the local setup and open the repository in [GitHub Codespaces](https://codespaces.new/tabler/tabler) or a VS Code Dev Container. The configuration in `.devcontainer/` installs Node.js, pnpm and all dependencies for you.

To set up Tabler for development on your own machine, follow these steps:

### Ensure Node.js and pnpm are installed

You'll need Node.js (v22.12 or higher) and pnpm to compile Tabler's files. If you don't have them installed, download and install them from the official websites:

- [Node.js](https://nodejs.org/)
- [pnpm](https://pnpm.io/) (we use pnpm over other package managers for faster installation).

### Install dependencies

Run the following command to install all required npm packages:

```bash
pnpm install
```

### Start developer mode

Use the following command to enable autocompilation with live reload. This will start up the preview website at `http://localhost:3000/`, and the documentation website at `http://localhost:3010/`:

```bash
pnpm run dev
```

### Make changes

Make your changes in the appropriate folders, such as `./core/`, `./preview/` or `./docs/`. Avoid modifying files in any `dist` folders, as they are auto-generated during the build process and will be overwritten.

## Useful commands

These commands cover the most common development tasks. Run them from the repository root:

| Command             | What it does                                        |
| ------------------- | --------------------------------------------------- |
| `pnpm run dev`      | Start preview and docs dev servers with live reload |
| `pnpm run build`    | Production build of all packages                    |
| `pnpm run lint`     | Markdown, Prettier and SCSS variable checks         |
| `pnpm run lint:fix` | Auto-fix lint issues where possible                 |
| `pnpm run test`     | Run the test suites                                 |
| `pnpm run check`    | Lint plus TypeScript type checks                    |

## Project structure

Tabler is a pnpm monorepo. The packages you will work with most often are:

- `core/` - the framework itself: SCSS sources in `core/scss/` and JavaScript in `core/js/`. This is where CSS classes and components are defined.
- `preview/` - the demo website built with [Astro](https://astro.build). Pages live in `preview/pages/*.astro`.
- `docs/` - the documentation website, also built with Astro. Pages live in `docs/pages/**/*.mdx`.
- `shared/` - Astro components, layouts and helpers shared by the preview and docs websites. Import UI with `@ui` (for example `import Button from '@ui/Button.astro'`), other shared pieces with `@shared`. Also holds `data/` (`@data`) and `static/`.
- `shared/data/` - JSON data used by demo pages. Import it with the `@data` alias.

A few practical rules:

- If you add a new CSS class or component style, change it in `core/scss/` and show it on a preview page.
- If you add or change a reusable piece of markup, put it in `shared/components/`, not in a single page.
- If you add a new feature, document it in `docs/pages/`.

## Add a changeset

If your change affects any package (new feature, bug fix, new page), add a changeset - a short note used to build the changelog:

```bash
pnpm exec changeset
```

Select the affected packages (`@tabler/core`, `@tabler/preview` or `@tabler/docs`), pick the bump type (`patch` for fixes, `minor` for new features) and write a one-sentence description, for example: `Added .btn-ghost variant for buttons.`

## Compiling for production

Before submitting a pull request, ensure your changes are properly compiled and tested:

1. Compile the production files

	```bash
	pnpm run build
	```

2. Test all pages to confirm everything works as expected.

## Submitting your contribution

Once your changes are ready, create a pull request (PR) on GitHub:

1. Branch off `dev` and name the branch `<type>/<short-description>`, for example `feat/gh-123-add-stepper-component` or `fix/markdown-table-overflow`. Allowed types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `build`, `ci`, `perf`, `style`, `revert`.
2. Write the PR in English: a concise title in present tense (max ~72 characters, no trailing period) and a short description that explains why the change is needed.
3. Keep the scope small - one logical change per pull request makes reviews faster.

Thank you for contributing to Tabler!