---
url: /flexily/CONTRIBUTING.md
---
# Contributing to Flexily

Thanks for your interest in contributing to Flexily! This guide covers the essentials.

## Prerequisites

* **Bun** >= 1.0 (runtime and package manager)
* **Node.js** >= 23.6 for development (native TS type-stripping); the published package supports Node >= 18
* **TypeScript** >= 5.7

## Getting Started

```bash
git clone https://github.com/beorn/flexily.git
cd flexily
bun install
bun run build       # Compile TypeScript
bun run typecheck   # Type check without emitting
```

## Running Tests

```bash
bun test                    # All tests (1774)
bun test tests/layout.test.ts   # Specific test file
bun test --watch            # Watch mode
```

The most important test layer is the **re-layout consistency suite** (1200+ fuzz tests). Always run it after layout changes:

```bash
bun test tests/relayout-consistency.test.ts
```

## Running Benchmarks

Performance is Flexily's core value proposition. Any change touching hot paths (`src/layout-zero.ts`, `src/node-zero.ts`) **must** include benchmark verification.

```bash
# 1. Check for CPU-heavy processes that would skew results
top -l 1 -n 5 -stats command,cpu | head -10

# 2. Capture baseline BEFORE changes
bun bench bench/yoga-compare-warmup.bench.ts > /tmp/bench-before.txt

# 3. Make your changes...

# 4. Re-check CPU load (must match pre-change conditions)
top -l 1 -n 5 -stats command,cpu | head -10

# 5. Capture AFTER changes
bun bench bench/yoga-compare-warmup.bench.ts > /tmp/bench-after.txt

# 6. Compare
diff /tmp/bench-before.txt /tmp/bench-after.txt
```

**Acceptable performance impact**: < 5% regression for minor features; no regression for refactoring.

## Code Structure

```
src/
├── index.ts        # Main export
├── node-zero.ts    # Node class with FlexInfo (hot path)
├── layout-zero.ts  # Layout algorithm (~2700 lines, hot path)
├── constants.ts    # Flexbox constants (Yoga-compatible)
├── types.ts        # TypeScript interfaces
├── utils.ts        # Shared utilities
└── classic/        # Allocating algorithm (for debugging)
```

See `docs/` for detailed documentation on the algorithm, API, performance, and testing methodology.

## Pull Request Guidelines

1. **Run the full test suite** (`bun test`) — all 1774 tests must pass
2. **Run `bun run typecheck`** — no type errors
3. **Benchmark if touching hot paths** — include before/after numbers in the PR description
4. **Keep Yoga API compatibility** — don't break the public API surface
5. **Don't allocate in hot paths** — `layout-zero.ts` avoids `new` in layout loops by design
6. **Don't add WASM** — pure JavaScript is the point

## Architecture Principles

* **Zero-allocation design** in the layout engine — reuses FlexInfo objects
* **Yoga API compatibility** — same constants, same method names
* **Two algorithms**: zero (production, zero-alloc) and classic (debugging, allocating)

For the full development workflow and detailed guidance, see [AGENTS.md](https://github.com/beorn/flexily/blob/main/AGENTS.md).

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](https://github.com/beorn/flexily/blob/main/LICENSE).