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