Contributing

March 31, 2026 ยท View on GitHub

Bug fix pull requests always welcome! For new features, please open an issue first to discuss.

Setup

git clone https://github.com/janosh/matterviz
cd matterviz
npm install

Development

Start the dev server:

npx vite
# or
npm run dev

Testing

Run all tests:

npx vitest
# or
npm test

Run Playwright end-to-end (E2E) tests:

npx playwright test

Test Requirements

New features should include tests. Bug fixes should include a test that fails on the old code and passes with your fix.

  • Unit tests go in tests/vitest/
  • E2E tests go in tests/playwright/
  • Test functions should have typing annotations and concise docstrings explaining what they test.

Before you start committing, create and check out a descriptively named branch:

git checkout -b cool-new-feature
# or
git checkout -b bug-fix-for-something

Making a Release

  1. Update version in package.json (follows semver)

  2. Generate changelog:

    npx tsx https://github.com/janosh/workflows/raw/refs/heads/main/scripts/make-release-notes.ts

  3. Commit and tag:

    git add package.json changelog.md readme.md
git commit -m "v1.2.3"
git tag v1.2.3
git push && git push --tags

  4. Create GitHub release