Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
82 lines (56 loc) · 3.16 KB

CONTRIBUTING.md

File metadata and controls

82 lines (56 loc) · 3.16 KB

Contributing to next-shell

Thanks for your interest in @jonmatum/next-shell. This document covers the setup and the conventions you need to know.

Prerequisites

  • Node.js 22 (see .nvmrc)
  • pnpm 10+

Setup

pnpm install

Day-to-day commands

Command What it does
pnpm build Build all packages via tsup
pnpm dev Watch-build all packages
pnpm lint Run ESLint across the repo
pnpm format Format everything with Prettier
pnpm format:check Verify formatting (used in CI)
pnpm typecheck Run tsc --noEmit across packages
pnpm test Run Vitest once
pnpm test:watch Run Vitest in watch mode

A pre-commit hook runs lint-staged — it will fix fixable issues automatically.

The semantic-token rule

The single most important rule in this repo is: no raw color values in component source.

This is enforced by the custom next-shell/no-raw-colors ESLint rule:

  • No hex literals (#fff, #abcdef, ...)
  • No raw CSS color functions (rgb(), hsl(), oklch(), ...)
  • No Tailwind palette utilities (bg-red-500, text-slate-700, bg-white, bg-black, ...)

Use semantic tokens instead: bg-background, text-foreground, border-border, bg-primary, text-primary-foreground, bg-destructive, etc.

Token definition files (anything under src/tokens/ or matching tokens.css) are exempt — those are where the mapping to real colors lives.

Commit conventions

We use Conventional Commits:

feat(layout): add Sidebar floating variant
fix(primitives): correct tooltip positioning in RTL
chore(ci): cache pnpm store

Pull requests

  • Target main
  • Keep PRs focused on a single issue
  • Include tests for behavior changes
  • Fill out the PR template

Breaking Changes

Any change that falls into the categories below is considered a breaking change:

  • Token renames or removals — changes to tokens.css, preset.css, or the colorTokens array in src/tokens/index.ts
  • Removed exports — a named export dropped from any public subpath barrel
  • Changed component props — required prop added, prop type narrowed, prop renamed or removed
  • CSS class / data-attribute changes — data-theme attribute renamed, Tailwind utility class prefix changed
  • Peer dependency bumps — minimum React, Next.js, or Tailwind version increased
  • Subpath removals — a package.json#exports entry removed or path changed

When introducing a breaking change:

  1. Add a new version section to packages/next-shell/MIGRATION.md following the template at the top of that file.
  2. Include before/after code snippets and step-by-step migration instructions.
  3. Mention the breaking change prominently in the PR description.
  4. Update the docs migration page at apps/docs/content/docs/migration/index.mdx.

Releasing

Releases are automated via Changesets (lands in Phase 10). Don't publish manually.