From 668983e1a63efb7618049c73cf9dcad2a5977a4e Mon Sep 17 00:00:00 2001 From: James Russo Date: Wed, 11 Nov 2026 10:55:59 +0000 Subject: [PATCH] fix(cli): preview uses the bundled Studio unless local Studio mode is opted in (#7551) Local Studio mode runs Vite in the resolved @hyperframes/studio folder, so the project folder decided which config and binary ran. Use it only when the project resolves to the same Studio the CLI itself resolves (a source checkout running its own build) or when HYPERFRAMES_LOCAL_STUDIO=1 is set; otherwise serve the embedded Studio. Co-authored-by: Claude Opus 5.5 --- docs/packages/cli.mdx | 7 +- packages/cli/src/commands/preview.test.ts | 78 ++++++++++++++++++++++- packages/cli/src/commands/preview.ts | 66 +++++++++++++------ 3 files changed, 128 insertions(+), 23 deletions(-) diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 595b2b8e84..83f66edfc7 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -1065,8 +1065,11 @@ sub-compositions refresh live. Preview and render share the same runtime. The server picks one of three modes by itself: **embedded** (the default for `npx` — Studio bundled in the CLI, no extra dependencies), **local studio** -(Vite with full HMR, when `@hyperframes/studio` is in your `node_modules`), or -**monorepo** (the studio dev server, when you run from the source repo). +(Vite with full HMR, from a `@hyperframes/studio` source checkout), or +**monorepo** (the studio dev server, when you run from the source repo). Local +studio mode runs only when the project resolves to the same Studio checkout as +the CLI itself, or when you set `HYPERFRAMES_LOCAL_STUDIO=1`; a Studio in the +project's own `node_modules` is not used otherwise. `--background` works with the embedded server only. The CLI ships GSAP, CustomEase, and MotionPathPlugin, so the GSAP scripts diff --git a/packages/cli/src/commands/preview.test.ts b/packages/cli/src/commands/preview.test.ts index eea55a0210..e6c960bfb4 100644 --- a/packages/cli/src/commands/preview.test.ts +++ b/packages/cli/src/commands/preview.test.ts @@ -1,4 +1,12 @@ -import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; +import { + chmodSync, + existsSync, + mkdirSync, + mkdtempSync, + realpathSync, + rmSync, + writeFileSync, +} from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; @@ -15,6 +23,7 @@ import { prebuildPreview, handlePreviewKillAll, handlePreviewList, + localStudioDir, previewHostAppError, previewLaunchMode, previewLaunchModeError, @@ -407,6 +416,59 @@ describe("previewLaunchMode", () => { }); }); +/** A project folder that carries its own @hyperframes/studio with a Vite config and binary. */ +function projectWithOwnStudio(): { project: string; studio: string; marker: string } { + const root = mkdtempSync(join(tmpdir(), "hf-preview-own-studio-")); + tempDirs.push(root); + const project = join(root, "project"); + const studio = join(project, "node_modules", "@hyperframes", "studio"); + const bin = join(project, "node_modules", ".bin"); + const marker = join(root, "ran"); + mkdirSync(studio, { recursive: true }); + mkdirSync(bin, { recursive: true }); + writeFileSync(join(project, "package.json"), '{"name":"project"}'); + writeFileSync(join(studio, "package.json"), '{"name":"@hyperframes/studio","version":"0.0.0"}'); + writeFileSync( + join(studio, "vite.config.ts"), + `require("node:fs").writeFileSync(${JSON.stringify(marker)}, "config");\nexport default {};\n`, + ); + writeFileSync(join(bin, "vite"), `#!/bin/sh\necho bin > ${JSON.stringify(marker)}\n`); + chmodSync(join(bin, "vite"), 0o755); + return { project, studio: realpathSync(studio), marker }; +} + +describe("localStudioDir", () => { + const interactive = { background: false, foreground: false, interactive: true, devMode: false }; + + it("serves the bundled Studio when the project brings its own", () => { + const { project } = projectWithOwnStudio(); + const dir = localStudioDir(project, {}); + expect(dir).toBeNull(); + expect(previewLaunchMode({ ...interactive, localStudio: dir !== null })).toBe("embedded"); + }); + + it("ignores a Studio in a parent folder's node_modules", () => { + const { project } = projectWithOwnStudio(); + const nested = join(project, "nested"); + mkdirSync(nested); + writeFileSync(join(nested, "package.json"), '{"name":"nested"}'); + expect(localStudioDir(nested, {})).toBeNull(); + }); + + it("uses the project's Studio when the user opts in", () => { + const { project, studio } = projectWithOwnStudio(); + const dir = localStudioDir(project, { HYPERFRAMES_LOCAL_STUDIO: "1" }); + expect(dir).toBe(studio); + expect(previewLaunchMode({ ...interactive, localStudio: dir !== null })).toBe("local"); + }); + + it("uses the project's Studio when it is the CLI's own", () => { + const { project, studio } = projectWithOwnStudio(); + expect(localStudioDir(project, {}, studio)).toBe(studio); + expect(localStudioDir(project, {}, join(studio, "elsewhere"))).toBeNull(); + }); +}); + describe("preview lifecycle JSON failures", () => { it.each([ [ @@ -743,6 +805,20 @@ describe("studio dev-server spawns", () => { expect(spawn).toHaveBeenCalledOnce(); expect(spawn.mock.calls[0]?.[2]).toMatchObject({ windowsHide: true }); }); + + it("runLocalStudioMode spawns nothing from a Studio the project brings", async () => { + const spawn = mockStudioSpawn(); + vi.stubEnv("HYPERFRAMES_LOCAL_STUDIO", ""); + const { project, marker } = projectWithOwnStudio(); + try { + const { runLocalStudioMode } = await import("./preview.js"); + await runLocalStudioMode(project, { json: true }); + expect(spawn).not.toHaveBeenCalled(); + expect(existsSync(marker)).toBe(false); + } finally { + vi.unstubAllEnvs(); + } + }); }); describe("preview inside a host app's agent run", () => { diff --git a/packages/cli/src/commands/preview.ts b/packages/cli/src/commands/preview.ts index e2ce0c36c8..8d65fbd40d 100644 --- a/packages/cli/src/commands/preview.ts +++ b/packages/cli/src/commands/preview.ts @@ -33,7 +33,15 @@ export const examples: Example[] = [ "hyperframes preview --lint-verbose", ], ]; -import { existsSync, lstatSync, mkdirSync, readlinkSync, symlinkSync, unlinkSync } from "node:fs"; +import { + existsSync, + lstatSync, + mkdirSync, + readlinkSync, + realpathSync, + symlinkSync, + unlinkSync, +} from "node:fs"; import { resolve, dirname, basename, join } from "node:path"; import { fileURLToPath } from "node:url"; import { createRequire } from "node:module"; @@ -492,7 +500,7 @@ export default defineCommand({ foreground: Boolean(args.foreground), interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY), devMode: isDevMode(), - localStudio: hasLocalStudio(dir), + localStudio: localStudioDir(dir) !== null, }); const hostAppError = previewHostAppError(launchMode); @@ -1517,27 +1525,37 @@ export async function runDevMode(dir: string, options?: StudioLaunchOptions): Pr return waitForStudioChildClose(child); } -/** - * Whether the project's local @hyperframes/studio can actually be SERVED. - * - * Local mode runs `vite` with the studio package as its cwd, so it needs that - * package's own `vite.config.ts` — which the published tarball does not carry - * (`files: ["src", "dist"]`). Resolving the package alone therefore is not - * enough: an npm-installed studio would send `preview` down a path that can - * never come up, and since `--background` re-execs this same CLI, it would time - * out after ten seconds instead of falling back. Fall back to embedded mode, - * which serves the same studio and does work from a published install. - */ -function hasLocalStudio(dir: string): boolean { +/** Set to 1 to let `preview` serve the project's own @hyperframes/studio with Vite. */ +export const LOCAL_STUDIO_ENV = "HYPERFRAMES_LOCAL_STUDIO"; + +function studioPackageDir(from: string): string | null { try { - const req = createRequire(join(dir, "package.json")); - const studioPkgPath = dirname(req.resolve("@hyperframes/studio/package.json")); - return existsSync(join(studioPkgPath, "vite.config.ts")); + const req = createRequire(from); + return realpathSync(dirname(req.resolve("@hyperframes/studio/package.json"))); } catch { - return false; + return null; } } +/** + * The @hyperframes/studio folder local mode may serve with Vite, or null for embedded mode. + * It needs the package's own `vite.config.ts`, which the published tarball lacks, so an + * npm-installed studio falls back to embedded instead of a launch that never comes up. + * Vite runs that config and the `vite` beside it as code, and a project folder (or a + * parent's node_modules) must not choose that code: the project's Studio is used only when + * it is the one the CLI itself resolves (a source checkout) or HYPERFRAMES_LOCAL_STUDIO=1. + */ +export function localStudioDir( + dir: string, + env: NodeJS.ProcessEnv = process.env, + cliStudioDir: string | null = studioPackageDir(fileURLToPath(import.meta.url)), +): string | null { + const studioDir = studioPackageDir(join(dir, "package.json")); + if (!studioDir || !existsSync(join(studioDir, "vite.config.ts"))) return null; + if (env[LOCAL_STUDIO_ENV] === "1") return studioDir; + return studioDir === cliStudioDir ? studioDir : null; +} + /** * Local studio mode: spawn Vite using a locally installed @hyperframes/studio. * Provides full Vite HMR and the complete studio experience. @@ -1546,8 +1564,16 @@ export async function runLocalStudioMode( dir: string, options?: StudioLaunchOptions, ): Promise { - const req = createRequire(join(dir, "package.json")); - const studioPkgPath = dirname(req.resolve("@hyperframes/studio/package.json")); + const studioPkgPath = localStudioDir(dir); + if (!studioPkgPath) { + reportPreviewFailure( + Boolean(options?.json), + "start", + "preview-start-failed", + `No local Studio to run for this project; set ${LOCAL_STUDIO_ENV}=1 to use the project's own @hyperframes/studio.`, + ); + return; + } const pName = options?.projectName ?? basename(dir); // Symlink project into studio's data directory