Contributing to Illuma Core

January 31, 2026 ยท View on GitHub

Setup

We use Bun as our package manager and runtime.

  1. Install Bun: Make sure Bun is installed (version matching the packageManager of package.json is recommended).
  2. Install Dependencies:
bun install

Workflow

Here are the some commands to check your changes comply with our standards:

Linting & formatting (With Biome).

bun run lint      # Checks for issues
bun run lint:fix  # Fixes auto-fixable issues

Type checking (With TypeScript):

bun run typecheck

Testing (With Vitest):

bun run test

Building (with tsup):

bun run build

CI/CD Checks

When you submit a Pull Request, GitHub Actions will automatically do:

  • Linting and code formatting check (lint)
  • Type validity check (typecheck)
  • Unit tests (test)

What to contribute

  • Bug fixes: Please provide a minimal reproduction first, then submit a PR with a fix.
  • New Features: Ideally, open an issue to discuss it before implementing. When implementing, please make sure to cover it with tests and update relevant documentation.
  • Clearer documentation: If you find any a section confusing or incomplete, please submit improvements.
  • Tests: Adding tests for cases you ran into or for new features is highly appreciated.

What to avoid

  • External dependencies: We aim to keep the library secure. PR's introducing new dependencies will be rejected.
  • Breaking changes without discussion: Changes that break backward compatibility must be discussed and approved first. Those will only be merged in major releases.
  • Code style changes: Please adhere to the existing code style. Large-scale reformatting or refactoring without functional changes will not be accepted.
  • AI-generated code: We do not accept functional contributions that are primarily generated by agents. Yet you may use AI tools to assist with writing tests and documentation.

Note on planning a revolution in the tools we use

We're are always interested in improving our development workflow and pipelines.

If you would like to suggest using a new tool, please open a separate issue for discussion. Please avoid mixing changes to tooling with other contributions (you will likely be asked to separate them).