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.

Contributions are welcome, from a typo fix to a new component. If you haven't contributed to open source before, the how to contribute guide explains the basics.

Not sure where to start? Look for issues labeled good first issue - they are small and well-scoped.

Contribution requirements

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

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

Installation

Follow these steps to set up Tabler for development:

Fork the repository: Guide to forking.

Clone the repository to your local machine:

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

Create a new branch for your changes:

# 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 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
pnpm (we use pnpm over other package managers for faster installation).

Install dependencies

Run the following command to install all required npm packages:

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/:

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

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:

Compile the production files
```
pnpm run build
```
Test all pages to confirm everything works as expected.

Submitting your contribution

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

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.
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.
Keep the scope small - one logical change per pull request makes reviews faster.

Thank you for contributing to Tabler!

Menu