Files
hyperframes/scripts/check-cli-lazy-deps.mjs
Miguel Ángel 5583ae4293 perf(cli): commands run without esbuild, puppeteer-core or sharp until they need them (#5930)
* perf(cli): commands run without esbuild, puppeteer-core or sharp until they need them

A host that bundles the CLI can now leave these packages out: each command
loads them only where it uses them, and sharp installs once on first use when
it is missing. The build check fails on any static import of them again.

* fix(cli): use a host's sharp from NODE_PATH and let hosts turn first-use installs off

* fix(cli): capture fails when sharp is missing, and one install serves every caller

A missing sharp now stops the asset download up front instead of counting every
image as unavailable. Concurrent first uses share one install, a failed install
is not retried in the same run, and preview thumbnails report why. Hosts can turn
off installs for a list of packages, e.g. HYPERFRAMES_NO_OPTIONAL_INSTALL=sharp.

* fix(cli): snapshot --describe still works without sharp, resizing only when it is installed

* style(cli): format the sharp loader and its tests

* build(cli): sharp is an optional dependency, so a host can ship the CLI without it

* build(studio-server): keep sharp out of the bundle now that it is optional
2026-10-20 09:12:47 +00:00

54 lines
2.1 KiB
JavaScript

import { existsSync, readFileSync, readdirSync } from "node:fs";
import { join, relative } from "node:path";
import { fileURLToPath } from "node:url";
import ts from "typescript";
const ROOT = join(import.meta.dirname, "..");
/** Loaded on first use, so a host may ship the CLI without them and commands that never need them still run. */
export const LAZY_PACKAGES = ["esbuild", "puppeteer-core", "sharp"];
function lazyPackage(specifier) {
return LAZY_PACKAGES.find((name) => specifier === name || specifier.startsWith(`${name}/`));
}
export function listStaticLazyImports(source, filename = "chunk.js") {
const sourceFile = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true);
return sourceFile.statements.flatMap((statement) => {
const isImportOrExport = ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement);
const specifier = isImportOrExport ? statement.moduleSpecifier : undefined;
if (!specifier || !ts.isStringLiteral(specifier) || statement.importClause?.isTypeOnly)
return [];
const name = lazyPackage(specifier.text);
if (!name) return [];
const { line } = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile));
return [`${filename}:${line + 1} imports ${specifier.text} statically`];
});
}
export function checkCliLazyDeps(root = ROOT) {
const dist = join(root, "packages/cli/dist");
if (!existsSync(dist)) return [`${relative(root, dist)} is missing; build the CLI first`];
return readdirSync(dist, { recursive: true })
.filter((name) => /\.m?js$/.test(name))
.flatMap((name) =>
listStaticLazyImports(
readFileSync(join(dist, name), "utf8"),
relative(root, join(dist, name)),
),
);
}
function main() {
const issues = checkCliLazyDeps();
if (issues.length > 0) {
console.error(`Load ${LAZY_PACKAGES.join(", ")} with a dynamic import where they are used:`);
issues.forEach((issue) => console.error(`- ${issue}`));
process.exitCode = 1;
return;
}
console.log(`CLI build loads ${LAZY_PACKAGES.join(", ")} only on first use.`);
}
if (process.argv[1] === fileURLToPath(import.meta.url)) main();