James Russo
cd17074f3b
## What Restructures the README to lead with skills-first onboarding, adds a demo GIF, surfaces the catalog, fixes incorrect pnpm references in contributing docs, and corrects the HTML example to use actual attribute names. ## Why The README told a CLI-first story while the homepage (hyperframes.heygen.com) tells an AI-agent-first story. For a project that brands itself "built for agents," the GitHub landing page should match. Additionally, 50+ catalog blocks were invisible from GitHub, the player and shader-transitions packages were missing from the packages table, and the contributing docs referenced pnpm while the repo uses bun. ## How **README changes:** - Quick Start restructured: skills install as Option 1 (recommended), manual CLI as Option 2 - Added demo GIF rendered with HyperFrames itself (HTML + GSAP composition → MP4 → GIF) - Added Catalog section with install examples and link - Added `@hyperframes/player` and `@hyperframes/shader-transitions` to packages table - Added npm downloads badge - Fixed HTML example: `data-track` → `data-track-index`, added missing `class="clip"` on img - Condensed Skills section into a concise table - Documentation link now points to `/introduction` (Mintlify docs) instead of the landing page **testing-local-changes.mdx:** - All `pnpm` references replaced with `bun` (14 occurrences) - Path references updated from `hyperframes-oss` to `hyperframes` ## Test plan - [ ] Verify README renders correctly on GitHub (logo, badges, GIF, tables, code blocks) - [ ] Verify GIF loops and is readable at GitHub's default README width - [ ] Verify all links resolve (docs site, catalog, packages, contributing) - [ ] Read through testing-local-changes.mdx for any remaining pnpm references - [x] Documentation updated (if applicable)
133 lines
4.1 KiB
Plaintext
133 lines
4.1 KiB
Plaintext
---
|
||
title: Testing Local CLI Changes
|
||
description: How to test unreleased CLI changes outside the monorepo using your local build.
|
||
---
|
||
|
||
When you modify the CLI or any package it bundles (core, engine, producer, studio), you need to test those changes against real projects _outside_ the monorepo — the same way an end user would run `hyperframes preview`.
|
||
|
||
## Prerequisites
|
||
|
||
Build the monorepo first. Every time you change source files, rebuild before testing.
|
||
|
||
```bash
|
||
# From the monorepo root
|
||
bun run build
|
||
```
|
||
|
||
## Option 1: bun link (recommended)
|
||
|
||
`bun link` makes the `hyperframes` binary in your `$PATH` point at your local build. It survives across terminal sessions and auto-picks up new builds without re-linking.
|
||
|
||
```bash
|
||
# If you previously installed hyperframes globally, remove it first —
|
||
# a global install takes priority over bun link and shadows your local build.
|
||
npm uninstall -g hyperframes 2>/dev/null
|
||
|
||
# Link your local build
|
||
cd packages/cli
|
||
bun link
|
||
|
||
# Verify — should print your local version AND point to the monorepo
|
||
hyperframes --version
|
||
which hyperframes
|
||
```
|
||
|
||
Now use `hyperframes` normally in any directory:
|
||
|
||
```bash
|
||
cd ~/my-video-project
|
||
hyperframes preview .
|
||
```
|
||
|
||
**After every `bun run build`** the linked binary is already up to date — no re-linking needed.
|
||
|
||
To restore the published release when you're done:
|
||
|
||
```bash
|
||
bun unlink hyperframes
|
||
npm install -g hyperframes@latest
|
||
```
|
||
|
||
## Option 2: node alias (no PATH changes)
|
||
|
||
If you don't want to touch your global `$PATH`, add a shell alias or call `node` directly:
|
||
|
||
```bash
|
||
# Temporary alias for your current shell session
|
||
alias hyperframes="node /path/to/hyperframes/packages/cli/dist/cli.js"
|
||
|
||
# Or invoke directly
|
||
node /path/to/hyperframes/packages/cli/dist/cli.js preview .
|
||
```
|
||
|
||
Replace `/path/to/hyperframes` with your actual monorepo path.
|
||
|
||
## Option 3: npm pack (test the exact published artifact)
|
||
|
||
Use this when you want to verify what would actually ship in a release, including the bundled studio and examples.
|
||
|
||
```bash
|
||
cd packages/cli
|
||
npm pack
|
||
# Creates: hyperframes-<version>.tgz
|
||
|
||
# Test it in an isolated directory
|
||
mkdir /tmp/pack-test && cd /tmp/pack-test
|
||
npx /path/to/hyperframes/packages/cli/hyperframes-<version>.tgz init my-video
|
||
cd my-video
|
||
npx /path/to/hyperframes/packages/cli/hyperframes-<version>.tgz preview .
|
||
```
|
||
|
||
## Testing the fix branches
|
||
|
||
When validating a specific bug fix, extract one of the test project archives and run through the scenario:
|
||
|
||
```bash
|
||
# Example: testing audio-after-seek fix
|
||
unzip golden-lyric-video.zip && cd golden-lyric-video
|
||
hyperframes preview .
|
||
# 1. Press Play — confirm audio plays
|
||
# 2. Drag the timeline scrubber to a different position
|
||
# 3. Press Play again — audio should resume from the seeked position
|
||
```
|
||
|
||
Common test scenarios:
|
||
|
||
| Bug | Project | Steps |
|
||
|---|---|---|
|
||
| Audio silent after seek | `golden-lyric-video` | Play → seek → play again, verify audio |
|
||
| Render stuck at 0% | any | Renders tab → Export → watch progress bar |
|
||
| Download 404 after restart | any | Complete a render → `Ctrl+C` → restart → Download |
|
||
| Timeline stops early | `intro-vid` | Play → should reach `0:05`, not stop at `0:03` |
|
||
| Lottie missing | `hyperframe-build-up-demo` | Play → rocket visible during 0–2 s |
|
||
| Blank thumbnails | any | Compositions sidebar should show previews |
|
||
|
||
## Troubleshooting
|
||
|
||
**Changes not reflected after `bun run build`**
|
||
|
||
The CLI binary is a single bundled file at `packages/cli/dist/cli.js`. If your change is in `@hyperframes/core` or another workspace package, make sure `bun run build` rebuilt _all_ packages — the CLI bundles its dependencies at build time.
|
||
|
||
**`hyperframes` still shows the old version / old UI**
|
||
|
||
A globally installed `hyperframes` package shadows `bun link`. Check which binary is active:
|
||
|
||
```bash
|
||
which hyperframes
|
||
```
|
||
|
||
If it points to a global store rather than your monorepo, remove the global install and re-link:
|
||
|
||
```bash
|
||
npm uninstall -g hyperframes
|
||
cd packages/cli && bun link
|
||
```
|
||
|
||
**Port already in use**
|
||
|
||
`hyperframes preview` defaults to port 3002 and auto-increments if it's taken. Pass `--port` to use a specific port:
|
||
|
||
```bash
|
||
hyperframes preview . --port 4000
|
||
```
|