Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hyperframes.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Studio Editing Work

If you are changing Studio’s visual editing surface, read 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

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