mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
ukimsanov
68 lines
2.5 KiB
Plaintext
68 lines
2.5 KiB
Plaintext
---
|
|
title: Contribute to the Catalog
|
|
description: Add a reusable block or component to the HyperFrames registry.
|
|
---
|
|
|
|
The Catalog is generated from the registry in the HyperFrames repository. Add a **block** for a complete composition or a **component** for a reusable snippet.
|
|
|
|
## Choose the item type
|
|
|
|
| Type | Use it for | Required files |
|
|
| --- | --- | --- |
|
|
| Block | A standalone composition with fixed dimensions and duration | `registry-item.json` and the composition HTML |
|
|
| Component | A snippet installed into another composition | `registry-item.json`, the snippet HTML, and a standalone `demo.html` |
|
|
|
|
Each item has its own directory under `registry/blocks/` or `registry/components/`.
|
|
|
|
## Build the item
|
|
|
|
1. Fork and clone [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes).
|
|
2. Copy a nearby item of the same type as a starting point.
|
|
3. Rename the directory and update `registry-item.json`.
|
|
4. Add the item to `registry/registry.json`.
|
|
|
|
The manifest follows the [registry item schema](https://github.com/heygen-com/hyperframes/blob/main/packages/core/schemas/registry-item.json). Blocks declare `dimensions` and `duration`; components must not.
|
|
|
|
For a component, `demo.html` must be a complete composition that shows the effect and can be rendered by the Catalog preview pipeline.
|
|
|
|
## Validate it
|
|
|
|
Run the same gates used for normal compositions:
|
|
|
|
```bash
|
|
npx hyperframes lint
|
|
npx hyperframes check
|
|
```
|
|
|
|
Then test the installation from another project:
|
|
|
|
```bash
|
|
npx hyperframes add your-item --dir /tmp/hyperframes-catalog-test
|
|
```
|
|
|
|
Check the installed file, copied include snippet, and standalone playback. Registry items must be deterministic: no real-time clocks, unseeded randomness, or render-time network dependencies.
|
|
|
|
## Generate the Catalog page
|
|
|
|
```bash
|
|
npx tsx scripts/generate-catalog-pages.ts
|
|
```
|
|
|
|
The script regenerates the Catalog MDX, its index, and navigation from the registry manifests. Do not hand-edit a generated Catalog page.
|
|
|
|
To create the preview assets for one item:
|
|
|
|
```bash
|
|
npx tsx scripts/generate-catalog-previews.ts --only your-item
|
|
```
|
|
|
|
## Open the pull request
|
|
|
|
Include:
|
|
|
|
- the registry files and regenerated Catalog output;
|
|
- a short description of where the item is useful;
|
|
- a preview image or video so reviewers can judge it without checking out the branch.
|
|
|
|
The item should be readable, seek correctly at any frame, work when installed outside its source directory, and add something meaningfully reusable. A one-off demo belongs in Examples rather than the Catalog.
|