Contributing to Tabler

Thank you for wanting to contribute! This is a short overview — the full guide lives in the documentation: How to Contribute.

Ways to contribute

Pick a starter issue — issues labeled good first issue are small and well-scoped, and help wanted issues welcome community help.
Report a bug — use the bug report template. Include steps to reproduce and, if possible, a live example (for example a JSFiddle).
Suggest a feature — use the feature request template or start a discussion first if you are not sure.
Improve the documentation — docs live in docs/content/**/*.mdx and follow the same pull request workflow as code.
Submit a pull request — fixes and improvements are always welcome. For large changes, please open an issue or discussion first so we can align before you invest time.
Report a security issue — do not open a public issue; follow the security policy instead.

Quick start

Requirements: Node.js 22.12+ and pnpm.

pnpm install
pnpm run dev

This starts the preview website at http://localhost:3000 and the documentation at http://localhost:3010, both with live reload.

You can also skip the local setup entirely: 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.

Where things live

core/ — the framework: SCSS (core/scss/) and JavaScript (core/js/)
preview/ — demo website (Astro, pages in preview/pages/*.astro)
docs/ — documentation website (Astro, pages in docs/content/**/*.mdx)
shared/ — components and layouts shared by preview and docs (@shared alias), plus data/ and static/
shared/data/ — JSON data for demo pages (@data alias)

Do not edit dist/ folders — they are generated by the build.

Useful commands

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, SCSS variable and generated-token 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
`pnpm run html-diff:baseline`	Snapshot all rendered preview pages (needs the dev server)
`pnpm run html-diff`	Byte-compare rendered preview pages against the snapshot
`pnpm run generate-tokens`	Regenerate `shared/lib/tokens.ts` from the core SCSS maps

Two of these help with refactors:

html-diff proves a refactor does not change the rendered demo HTML: run html-diff:baseline before your change, refactor, then html-diff — it reports the first differing line per page and marks whitespace-only differences.
generate-tokens keeps the TS unions in shared/lib/tokens.ts in sync with the SCSS maps (colors, sizes, breakpoints, payment providers, flags). Edit the SCSS map, regenerate, commit both — a stale file fails pnpm run lint.

Before you open a pull request

Branch off dev and use the branch naming convention: <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.
Build and test: pnpm run build must pass. For docs changes, also run pnpm run lint.
Add a changeset if your change affects any package: pnpm exec changeset. Use one sentence starting with Added, Updated, Fixed or Removed, with backticks for code tokens (for example Added `.btn-ghost` variant for buttons.).
Write the PR in English: a concise title in present tense (max ~72 chars, 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 and releases safer.

Code style

Use Bootstrap 5 conventions and Tabler's CSS custom properties pattern: --component-property. Write custom properties without a prefix — the build adds the public --tblr- prefix. Names owned by a third-party library you are theming must be listed in cssVarIgnore in .build/css-var-prefix.ts so they stay untouched.
Write documentation in simple English: short sentences, common words, direct instructions.
Ensure changes work in all supported browsers (see the browser support docs).

Code of conduct

By participating, you agree to follow our Code of Conduct.

5.5 KiB Raw Permalink Blame History