tabler/CONTRIBUTING.md

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.

Docker

If you prefer not to install Node.js, build and run the provided image from the repository root:

docker build -t tabler .
docker run -p 3000:3000 -p 3010:3010 -v $(pwd)/core:/app/core -v $(pwd)/preview:/app/preview -v $(pwd)/docs:/app/docs -v $(pwd)/shared:/app/shared tabler

This mounts the source directories into the container and exposes the preview on port 3000 and the documentation on port 3010. Edit anything in core/, preview/, docs/ or shared/ and the browser refreshes after the rebuild.

Or use Docker Compose, which applies the same mounts and ports:

docker compose up --build

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

1. 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.
2. Build and test: pnpm run build must pass. For docs changes, also run pnpm run lint.
3. 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.).
4. 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.
5. Keep the scope small: one logical change per pull request makes reviews faster and releases safer.

Releases

Only three long-lived branches exist: main, dev and next. There are no release/* branches; a fix always ships from dev as the next patch of the current minor.

Branch	Holds	Releases
dev	the current minor: fixes, docs, chores	the next patch (1.7.1, 1.7.2, ...) as latest on npm
next	the next minor: new components, classes, pages	prereleases (1.8.0-next.0, -next.1, ...) under the npm tag next, no GitHub release
main	the last release	nothing; it builds docs.tabler.io

Every push to dev or next updates that branch's chore: update versions pull request; merging it publishes to npm. Open a pull request against dev for a fix and against next for a feature. A fix on next that users of the current version need goes to dev instead, and reaches next with the next sync.

After a patch release from dev: pnpm run release:main (on dev) refreshes the SRI hashes, merges dev into main and merges dev into next. Run it after every release from dev, so next never drifts.

Releasing the next minor (next becomes 1.8.0):

1. On next: pnpm exec changeset pre exit, commit .changeset/pre.json and push. The changesets consumed by the prereleases are still there; the final changelog lists all of them once.
2. Merge next into dev (a pull request, or a merge pushed to dev). The chore: update versions pull request on dev now shows 1.8.0; the .github/release-notes/1.8.0.md intro goes in before merging it.
3. Merge the version pull request, wait for npm, run pnpm run release:main.
4. Start the next line. dev now contains next, so it fast-forwards: git checkout next && git merge --ff-only dev && pnpm exec changeset pre enter next && git commit -am "Enter prerelease mode for 1.9" && git push. The first time, create the branch with git checkout -b next dev instead.

Never commit to main directly. Changes reach it only through release:main.

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.