mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-01 19:42:03 +00:00
Vance IngallsandClaude Opus 4.6
6e01980f41
The command starts a preview server — "preview" describes what users are doing more accurately than "dev". Updates the command name, file name, all CLI references, docs, skills, and template CLAUDE.md. 22 files updated across CLI source, docs, skills, and templates. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
137 lines
4.5 KiB
Plaintext
137 lines
4.5 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
|
||
pnpm build
|
||
```
|
||
|
||
## Option 1: pnpm link (recommended)
|
||
|
||
`pnpm link --global` 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 pnpm link and shadows your local build.
|
||
pnpm remove -g hyperframes 2>/dev/null || npm uninstall -g hyperframes 2>/dev/null
|
||
|
||
# Link your local build
|
||
cd packages/cli
|
||
pnpm link --global
|
||
|
||
# Verify — should print your local version AND point to the monorepo
|
||
hyperframes --version
|
||
which hyperframes
|
||
# The path should contain your monorepo, NOT pnpm/global/.pnpm/hyperframes@...
|
||
```
|
||
|
||
Now use `hyperframes` normally in any directory:
|
||
|
||
```bash
|
||
cd ~/my-video-project
|
||
hyperframes preview .
|
||
```
|
||
|
||
**After every `pnpm build`** the linked binary is already up to date — no re-linking needed.
|
||
|
||
To restore the published release when you're done:
|
||
|
||
```bash
|
||
pnpm unlink --global 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-oss/packages/cli/dist/cli.js"
|
||
|
||
# Or invoke directly
|
||
node /path/to/hyperframes-oss/packages/cli/dist/cli.js dev .
|
||
```
|
||
|
||
Replace `/path/to/hyperframes-oss` 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 templates.
|
||
|
||
```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-oss/packages/cli/hyperframes-<version>.tgz init my-video
|
||
cd my-video
|
||
npx /path/to/hyperframes-oss/packages/cli/hyperframes-<version>.tgz dev .
|
||
```
|
||
|
||
## 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 `pnpm 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 `pnpm 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 `pnpm link`. Check which binary is active:
|
||
|
||
```bash
|
||
which hyperframes
|
||
# BAD: /Users/you/Library/pnpm/hyperframes → pnpm/global/.pnpm/hyperframes@0.x.x/...
|
||
# GOOD: /Users/you/Library/pnpm/hyperframes → your-monorepo/packages/cli/dist/cli.js
|
||
```
|
||
|
||
If it points to the global store, remove the global install and re-link:
|
||
|
||
```bash
|
||
pnpm remove -g hyperframes
|
||
npm uninstall -g hyperframes # in case it was installed via npm
|
||
cd packages/cli && pnpm link --global
|
||
```
|
||
|
||
**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
|
||
```
|