Skip to main content
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. 
# From the monorepo root
pnpm build
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. 
# 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: 
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: 
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: 
# 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 preview .
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. 
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 preview .

​
Testing the fix branches

When validating a specific bug fix, extract one of the test project archives and run through the scenario: 
# 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:
BugProjectSteps
Audio silent after seekgolden-lyric-videoPlay → seek → play again, verify audio
Render stuck at 0%anyRenders tab → Export → watch progress bar
Download 404 after restartanyComplete a render → Ctrl+C → restart → Download
Timeline stops earlyintro-vidPlay → should reach 0:05, not stop at 0:03
Lottie missinghyperframe-build-up-demoPlay → rocket visible during 0–2 s
Blank thumbnailsanyCompositions 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: 
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: 
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: 
hyperframes preview . --port 4000