Thanks for considering a contribution! This guide helps you get productive quickly.
# Node version is read from .node-version
npm ci
npm run devUseful scripts
npm run dev— Vite dev servernpm run build— production buildnpm run lint/npm run typecheck— quality gatesnpm run test— unit tests (Vitest)npx playwright test— E2E (Playwright)npx changeset— create a release note & bump proposal
- Branches:
feat/<topic>,fix/<bug>,chore/<thing>. - Commits: Conventional Commits (e.g.,
feat(canvas): add bar hover). - PRs: small, focused; fill out the PR template; include screenshots for UI.
We use Husky. After npm ci:
bash scripts/husky.shThis enables pre-commit (lint/format) and commit-msg (commitlint).
Algorithms live in src/algorithms/<topic>/algos/. Current topics:
| Topic | Directory | Algorithms |
|---|---|---|
| sorting | src/algorithms/sorting/algos/ |
10 algorithms |
| searching | src/algorithms/searching/algos/ |
5 algorithms |
| graphs | src/algorithms/graphs/algos/ |
6 algorithms |
| trees | src/algorithms/trees/algos/ |
2 algorithms |
| strings | src/algorithms/strings/algos/ |
2 algorithms |
| dp | src/algorithms/dp/algos/ |
3 algorithms |
| linked-lists | src/algorithms/linked-lists/algos/ |
2 algorithms |
| arrays | src/algorithms/arrays/algos/ |
2 algorithms |
-
Create
src/algorithms/<topic>/algos/<name>.ts:import type { Algorithm } from "@/engine/types"; export const run: Algorithm = function* myAlgo(input: unknown) { const arr = input as number[]; yield { array: [...arr], highlights: {}, explain: "Starting...", pcLine: 1, }; // ... algorithm steps yielding Frame objects ... yield { array: [...arr], highlights: {}, explain: "Done!", pcLine: -1 }; };
-
Add an
AlgoMetaentry insrc/algorithms/<topic>/algos/index.tswith: slug, title, topic, summary, pseudocode, complexity, about, pros/cons, code (JS/Python/Java/C++), codeLineMap, andload: () => import("./<name>"). -
For new topics, also register in
src/engine/registry.tsand add to the topic union insrc/types/index.ts. -
Add unit tests in
src/tests/unit/. UsetestSortingAlgorithmhelper for sorting algorithms, or write manual frame checks for other categories. -
Each yielded frame must include
array(spread copy),explain, andpcLine. Usehighlights(compared,swapped,indices,pivot) for visual feedback.
- Keep React state minimal; draw to
<canvas>insideArrayCanvas. - Use the
ArrayCanvasHandlemethods fromVisualizerPageto trigger redraws on runner ticks.
- Unit:
vitest runfor lib and hooks (151+ tests). - E2E: run against
vite preview(CI does this automatically). - Avoid flakes (
await page.getByTestId(...).waitFor()).
- Keyboard reachable controls; visible focus rings.
- Use semantic roles (
role="slider", etc.) and ARIA attributes. - Strings are centralized via i18next (
src/i18n/); 5 languages supported.
- Avoid unnecessary re-renders; prefer memoized selectors.
- Keep per-frame work in canvas only; no heavy allocations on each tick.
- Significant decisions → add an ADR in
docs/ADR/(see template). - High-level architecture →
docs/ARCHITECTURE.md.
- Report vulnerabilities to security@algolens.app. Do not open public issues for sensitive reports.
- Use Changesets:
npx changesetto propose a bump.- CI opens/updates a Version Packages PR.
- Merging to
masterpublishes to npm and creates the GitHub release.
Thanks for helping make AlgoLens better!