Development

Prerequisites

• Node.js ^20.19.0 || >= 22.12.0 — the engines range oxlint and oxfmt declare. Node 21.x and 22.0–22.11 are not supported. CI runs the suite on Node 20, 22 and 24.
• npm — the repository ships a package-lock.json, so use npm ci, not yarn or pnpm. No other global tooling is needed.

The published bundle targets ES5 with zero runtime dependencies; that constraint is about the output, not about your machine. Do not add a runtime dependency — if you believe one is unavoidable, open an issue first and make the case.

Getting set up

git clone https://github.com/soimy/maxrects-packer.git
cd maxrects-packer
npm ci --include=dev     # --include=dev matters when NODE_ENV=production is set in your shell
npm test                 # builds dist/ and runs the vitest suite

NODE_ENV=production makes npm skip devDependencies, which is why --include=dev is spelled out everywhere in the repository's own documentation.

Scripts

Command	What it does
npm test	Clean build (dist/, lib/) then the full vitest suite.
npm run build	rollup bundle only; build:clean also removes the previous output.
npm run typecheck	Native TypeScript 7 type check; the script asserts the compiler version first.
npm run lint / lint:fix	oxlint over src, test, scripts and the docs config; baseline is 0 warnings / 0 errors.
npm run format / format:check	oxfmt writes back / checks, including docs/.vitepress/*.mts.
npm run cover	Coverage run plus the artifact self-check; writes test/coverage/ (gitignored).
npm run verify:package	Packs a tarball, installs it into a temp consumer and consumes it by package name; compiles the ESM type fixture under bundler, node16 and nodenext, and a CommonJS .cts one under node16 and nodenext. Needs a build first.
npm run verify:docs	Asserts the documentation boundary: tracked source, ignored build products, and what docs:clean may delete.
npm run docs:build	Generates docs/api/, builds the site into docs/.vitepress/dist/, writes the legacy-URL redirects, then checks the output.
npx vitest run test/maxrects-bin.spec.js	A single spec, no rebuild needed.

Worktrees

Parallel or isolated work belongs in a linked worktree under .worktrees/ (gitignored), so experiments never leak into the repository root:

git worktree add .worktrees/<branch> -b <branch>
cd .worktrees/<branch>
npm ci --include=dev      # each worktree has its own node_modules and dist

Never commit dist/, docs/api/, docs/.vitepress/{cache,dist}/, test/coverage/, node_modules/ or .worktrees/. The tracked documentation under docs/ is source, not output — see documentation.

Code style

• oxfmt owns formatting: 4-space indentation, double quotes, semicolons, printWidth 120, no trailing comma, no space between a function name and its parentheses. Run npm run format before committing instead of aligning anything by hand.
• oxlint reports warnings but only errors fail CI; four rules are deliberately set to warn (no-console, no-unused-vars, no-unneeded-ternary, jsdoc/require-property-type). Keep the run at 0/0 anyway, and use // oxlint-disable-next-line <rule> for a genuine exception rather than loosening the config.
• Keep explicit public / private modifiers, and give new public API JSDoc: @param entries use a - separator, @property entries carry a type. The API reference on this site is generated from those comments.
• Line endings are LF everywhere (.gitattributes sets * text=auto eol=lf); configure your editor instead of committing CRLF.

Branching

Branch off master with type/short-slug, matching the commit type you intend to use — fix/updatebinsize-edgy-placement, feat/non-exclusive-tags, docs/contributing-guide. Include the issue number when there is one: fix/54-expanding-one-dimension. One logical change per branch; unrelated cleanups belong in their own pull request.