mirror of
https://github.com/tabler/tabler.git
synced 2026-08-29 21:31:28 +04:00
137 lines
6.3 KiB
Plaintext
137 lines
6.3 KiB
Plaintext
---
|
||
title: How to contribute
|
||
summary: This guide explains how to contribute to Tabler, from setting up a development environment to making and testing changes. It covers essential steps like forking the repository, installing dependencies, and submitting a pull request to help improve Tabler's features and functionality.
|
||
description: Guide to contributing to Tabler and setting up for development.
|
||
---
|
||
import Example from '@components/Example.astro';
|
||
import Steps from '@components/Steps.astro'
|
||
|
||
Contributions are always welcome and highly encouraged! Whether you're new to open source or a seasoned contributor, your input helps make Tabler better for everyone. If you're new to open source, we recommend reading a [how to contribute](https://opensource.guide/how-to-contribute/) guide to learn more about contributing.
|
||
|
||
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:
|
||
|
||
<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.
|
||
</Steps>
|
||
|
||
## 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!
|