mirror of
https://github.com/tabler/tabler.git
synced 2026-08-05 01:44:41 +04:00
Paweł Kuna
115 lines
4.8 KiB
Plaintext
115 lines
4.8 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.
|
||
layout: '@shared/layouts/DocsMdxLayout.astro'
|
||
---
|
||
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.
|
||
|
||
## 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
|
||
|
||
To set up Tabler for development, 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>
|
||
|
||
## 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. Make sure to include a clear and concise description of the changes and their purpose. Thank you for contributing to Tabler!
|