Files
hyperframes/docs/packages/studio-server.mdx

139 lines
5.7 KiB
Plaintext

---
title: "@hyperframes/studio-server"
description: "Mount the Studio project and preview API in your own server."
---
`@hyperframes/studio-server` is the backend used by Studio. It serves projects
and previews, applies source mutations, creates thumbnails, and starts render
jobs.
Most users do not need it. The CLI wires the server and Studio together when
you run `npx hyperframes preview`. Use this package only when your own
application must host the Studio backend.
```bash
npm install @hyperframes/studio-server
```
## Mount the API
`createStudioApi()` returns a Hono application. The adapter is the boundary
between Studio and your project storage, bundler, linter, and renderer.
```ts
import type { Hono } from "hono";
import {
createStudioApi,
type StudioApiAdapter,
} from "@hyperframes/studio-server";
export function mountStudioApi(
app: Hono,
adapter: StudioApiAdapter,
) {
app.route("/api", createStudioApi(adapter));
}
```
When it is served from loopback (`localhost`, `127.0.0.1` or `[::1]`), Studio
sends its API requests without cookies, so they don't queue behind the
preview's media. On any other origin it sends them as usual, so remote and
proxied setups (Codespaces, tunnels, an access proxy) keep their cookies by
default. A loopback host that authenticates its mounted API with same-origin
cookies sets `VITE_STUDIO_API_SAME_ORIGIN_CREDENTIALS=true`, at build time or at
runtime in `window.__HF_STUDIO_ENV__`; it costs that host the connection
speedup.
Studio reads the flag once, when its modules load, so set
`window.__HF_STUDIO_ENV__` before loading Studio; the CLI injects it, but a host
that mounts the API itself must inject it too.
A `StudioApiAdapter` supplies:
- project listing and resolution;
- composition bundling and linting;
- render output storage and job startup;
- optional thumbnails, sessions, registry installation, and background removal.
Use the interface exported by your installed version as the exact contract. It
changes as Studio gains capabilities.
`bundle(projectDir, options)` must pass `options` through to `bundleToSingleHtml`,
spread over your own options. The preview sets `stampHfIds` there so each element
is served with the id its source file mints. If a host drops it, a composition
the bundler inlines can be served with ids that a later save does not mint.
```ts
bundle: (dir, options) => bundleToSingleHtml(dir, { runtime: "inline", ...options }),
```
## Serve GSAP from your own mirror
Studio can load the GSAP dependencies it adds from a local or private mirror
when jsDelivr is unavailable. Set `HYPERFRAMES_GSAP_BASE_URL` before starting
the preview server or creating the Studio API:
```bash
HYPERFRAMES_GSAP_BASE_URL=http://127.0.0.1:8080/vendor/npm \
npx hyperframes preview ./my-video
```
Serve the GSAP distribution files under that URL with this layout, using the
versions your compositions need:
```text
<mirror-root>/gsap@3.15.0/dist/gsap.min.js
<mirror-root>/gsap@3.15.0/dist/CustomEase.min.js
<mirror-root>/gsap@3.15.0/dist/MotionPathPlugin.min.js
```
Studio uses the mirror for the GSAP, CustomEase, and MotionPathPlugin scripts
it adds to previews, including dependencies loaded when you edit motion.
Keep `gsap@<version>` in authored GSAP URLs so the server can infer which
plugin version to add. When it cannot infer a version, it uses the framework's
default, currently `3.15.0`.
The base must be an absolute HTTP(S) URL without credentials, a query string,
or a fragment. Surrounding whitespace and trailing slashes are removed.
An unset or empty value uses `https://cdn.jsdelivr.net/npm`; an invalid
nonempty value stops API startup with a configuration error.
The server reads this setting once at startup. Restart it after changing the
value. For a managed CLI preview, run `npx hyperframes preview ./my-video --stop`
before starting it again with the new setting. Cached preview HTML is keyed
by the normalized mirror URL, so a different mirror takes effect after restart
without deleting the preview cache.
This setting changes only dependencies Studio adds. Your composition's own
script, font, image, and media URLs stay as authored; serve those locally too
for an offline project. If the selected mirror is unavailable or lacks a
requested file, Studio does not retry that dependency through jsDelivr.
## Other entry points
| Import | Purpose |
| --- | --- |
| `@hyperframes/studio-server/source-mutation` | Apply guarded changes to composition source |
| `@hyperframes/studio-server/screenshot-clip` | Calculate element screenshot geometry |
| `@hyperframes/studio-server/safe-path` | Resolve paths inside a project and walk its files, without the server |
| `@hyperframes/studio-server/hf-ids` | Stamp stable element ids into a project's HTML, without the server |
| `@hyperframes/studio-server/history` | Open a project's undo history, without the server |
| `@hyperframes/studio-server/manual-edits-render-script` | Reapply Studio manual edits during render |
| `@hyperframes/studio-server/studio-motion-render-script` | Reapply Studio motion edits during render |
| `@hyperframes/studio-server/draft-markers` | Work with draft gesture markers |
| `@hyperframes/studio-server/finite-mutation` | Guard source mutations against non-finite values |
| `@hyperframes/studio-server/media-proxy-preview` | Support proxied media in preview |
`@hyperframes/core/studio-api` remains a deprecated compatibility re-export.
New integrations should import from `@hyperframes/studio-server`.
## Related topics
<CardGroup cols={2}>
<Card title="@hyperframes/studio" icon="palette" href="/packages/studio">
Embed lower-level Studio interface components.
</Card>
<Card title="Studio guide" icon="display" href="/studio">
Use the complete editor that ships with HyperFrames.
</Card>
</CardGroup>