Skip to main content
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

bun run --filter @hyperframes/core test

​
Running All Tests

bun run --filter '*' test

​
Packages

PackagePathDescription
@hyperframes/corepackages/coreTypes, HTML generation, runtime, linter
@hyperframes/enginepackages/engineSeekable page-to-video capture engine
@hyperframes/producerpackages/producerFull rendering pipeline (capture + encode)
@hyperframes/studiopackages/studioComposition editor UI
hyperframespackages/cliCLI 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
  • Templates — create new starter templates
  • 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
  • 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.