Contributing

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

1. Fork and clone

   Fork the repository on GitHub, then clone your fork:

   git clone https://github.com/YOUR_USERNAME/hyperframes.git
   cd hyperframes
   
2. Install dependencies

   Hyperframes uses bun for package management:

   bun install
   
3. Build all packages

   Build the monorepo to ensure everything compiles:

   bun run build
   
4. Run the studio

   Start the development server to verify your setup:

   bun run dev
   

   If the studio opens at http://localhost:3000 with a preview, your environment is ready.

5. Create a branch

   Create a feature branch for your work:

   git checkout -b my-feature
   

Development

Common Commands

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

Running Tests

Core

bun run --filter @hyperframes/core test

bun run --filter @hyperframes/engine test

bun run --filter @hyperframes/core test:hyperframe-runtime-ci

cd packages/producer && bun run docker:build:test && bun run docker:test

Running All Tests

bun run --filter '*' test

Packages

Package	Path	Description
@hyperframes/core	packages/core	Types, HTML generation, runtime, linter
@hyperframes/engine	packages/engine	Seekable page-to-video capture engine
@hyperframes/producer	packages/producer	Full rendering pipeline (capture + encode)
@hyperframes/studio	packages/studio	Composition editor UI
hyperframes	packages/cli	CLI for creating, previewing, and rendering

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 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 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 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

GitHub Issues

Report bugs, request features, and discuss ideas.

Code of Conduct

Our community standards and expectations.

License

By contributing, you agree that your contributions will be licensed under the MIT License.