heygen-com--hyperframes/docs/contributing.mdx

---
title: Contributing
description: "How to contribute to Hyperframes."
---

Thanks for your interest in contributing to Hyperframes! This guide covers everything you need to get set up, run tests, and submit a pull request.

## Getting Started

<Steps>
  <Step title="Fork and clone">
    Fork the repository on GitHub, then clone your fork:
    ```bash
    git clone https://github.com/YOUR_USERNAME/hyperframes.git
    cd hyperframes
    ```
  </Step>
  <Step title="Install dependencies">
    Hyperframes uses [bun](https://bun.sh/) for package management:
    ```bash
    bun install
    ```
  </Step>
  <Step title="Build all packages">
    Build the monorepo to ensure everything compiles:
    ```bash
    bun run build
    ```
  </Step>
  <Step title="Run the studio">
    Start the development server to verify your setup:
    ```bash
    bun run dev
    ```
    If the studio opens at `http://localhost:3000` with a preview, your environment is ready.
  </Step>
  <Step title="Create a branch">
    Create a feature branch for your work:
    ```bash
    git checkout -b my-feature
    ```
  </Step>
</Steps>

## Development

### Common Commands

```bash
bun install                          # Install all dependencies
bun run dev                          # Start the studio (composition editor + live preview)
bun run build                        # Build all packages
bun run --filter '*' typecheck       # Type-check all packages
```

### Studio Editing Work

If you are changing Studio's visual editing surface, read
[Studio Manual DOM Editing](/contributing/studio-manual-dom-editing) before
editing code. The inspector intentionally exposes only interactions it can
persist safely back to HTML, so changes should preserve the capability gates,
source patching model, and documented limitations.

### Running Tests

<CodeGroup>
```bash Core
bun run --filter @hyperframes/core test
```
```bash Engine
bun run --filter @hyperframes/engine test
```
```bash Runtime Contract
bun run --filter @hyperframes/core test:hyperframe-runtime-ci
```
```bash Producer (Docker)
cd packages/producer && bun run docker:build:test && bun run docker:test
```
</CodeGroup>

### Running All Tests

```bash
bun run --filter '*' test
```

## Packages

| Package | Path | Description |
|---------|------|-------------|
| [`@hyperframes/core`](/packages/core) | `packages/core` | Types, HTML generation, runtime, linter |
| [`@hyperframes/sdk`](/packages/sdk) | `packages/sdk` | Headless composition editing engine |
| [`@hyperframes/engine`](/packages/engine) | `packages/engine` | Seekable page-to-video capture engine |
| [`@hyperframes/player`](/packages/player) | `packages/player` | Embeddable composition player |
| [`@hyperframes/producer`](/packages/producer) | `packages/producer` | Full rendering pipeline (capture + encode) |
| [`@hyperframes/shader-transitions`](/packages/shader-transitions) | `packages/shader-transitions` | WebGL shader transition engine |
| [`@hyperframes/aws-lambda`](/packages/aws-lambda) | `packages/aws-lambda` | AWS Lambda distributed rendering adapter |
| [`@hyperframes/gcp-cloud-run`](/packages/gcp-cloud-run) | `packages/gcp-cloud-run` | GCP Cloud Run distributed rendering adapter |
| [`@hyperframes/studio`](/packages/studio) | `packages/studio` | Composition editor UI |
| [`hyperframes`](/packages/cli) | `packages/cli` | CLI for creating, previewing, and rendering |
| `@hyperframes/sdk-playground` (private) | `packages/sdk-playground` | Local SDK playground app |

## What to Work On

Not sure where to start? Here are some ideas:

- **Good first issues** — look for issues labeled `good first issue` on GitHub
- **Documentation** — improve docs, add examples, fix typos
- **Linter rules** — add new rules to catch more composition mistakes
- **Examples** — create new starter examples
- **Bug fixes** — check the issue tracker for reported bugs

## Pull Requests

### Commit Format

Use [conventional commit](https://www.conventionalcommits.org/) format for all commits and PR titles:

```
feat: add timeline export
fix: resolve seek overflow at composition boundary
docs: add GSAP easing examples
refactor: extract frame buffer pool into shared module
test: add regression test for nested composition timing
```

### CI Requirements

All of the following must pass before your PR can be merged:

- **Build** — `bun run build` succeeds
- **Type check** — `bun run --filter '*' typecheck` reports no errors
- **Tests** — all test suites pass
- **Semantic PR title** — PR title follows conventional commit format

### Review Process

- PRs require at least 1 approval from a maintainer
- Keep PRs focused — one feature or fix per PR
- Target alpha-only PRs at `next` instead of `main`; see
  [Release channels](/contributing/release-channels) for branch policy details
- Include a clear description of what changed and why
- Add tests for new features and bug fixes

## Reporting Issues

- Use [GitHub Issues](https://github.com/heygen-com/hyperframes/issues) for bug reports and feature requests
- Search existing issues before creating a new one
- For bug reports, include:
  - Steps to reproduce
  - Expected behavior vs. actual behavior
  - Hyperframes version (`npx hyperframes info`)
  - Operating system and Node.js version

## Community

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/heygen-com/hyperframes/issues">
    Report bugs, request features, and discuss ideas.
  </Card>
  <Card title="Code of Conduct" icon="handshake" href="https://github.com/heygen-com/hyperframes/blob/main/CODE_OF_CONDUCT.md">
    Our community standards and expectations.
  </Card>
</CardGroup>

## License

By contributing, you agree that your contributions will be licensed under the [Apache 2.0 License](https://github.com/heygen-com/hyperframes/blob/main/LICENSE).