Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

23.4 KB
Raw Blame
import { createHash } from "node:crypto";
import { execFile } from "node:child_process";
import {
  access,
  copyFile,
  lstat,
  mkdir,
  readFile,
  readdir,
  rm,
  stat,
  symlink,
  writeFile,
} from "node:fs/promises";
import { createRequire } from "node:module";
import { join } from "node:path";
import { chdir, cwd } from "node:process";
import { promisify } from "node:util";
import { log } from "@clack/prompts";
import {
  projectPreviewSources,
  type ProjectPreviewSource,
} from "@webstudio-is/project-build/preview";
import { sanitizeValidationDetail } from "@webstudio-is/project-build/runtime";
import { generatedFilesManifest, prebuild } from "../prebuild";
import { LOCAL_CONFIG_FILE, LOCAL_DATA_FILE } from "../config";
import { HandledCliError } from "../errors";
import {
  getPreviewUrl,
  getNodeRuntimeEnv,
  previewBuildCacheMarker,
  previewProcessOwnerFile,
  runPreviewBuild,
  resolvePreviewPackageManager,
  startPreviewServer,
  waitForPreviewExit,
} from "../preview-server";
import type {
  CommonYargsArgv,
  StrictYargsOptionsToInterface,
} from "./yargs-types";
import { buildOptions } from "./build";
import { sync, defaultSyncDependencies, type SyncDependencies } from "./sync";
import { resolveApiConnection } from "../api-connection";
import {
  createCliProjectSession,
  writeCliProjectSessionPreviewDataFile,
} from "../project-session";
import { LOCAL_ASSETS_DIR } from "../asset-files";
import packageJson from "../../package.json" with { type: "json" };
import { createExclusiveAsyncRunner } from "../async-utils";

export const previewDefaultTemplate = ["react-router"] as const;
export const previewSources = projectPreviewSources;
export type PreviewSource = ProjectPreviewSource;

const getPreviewTemplates = (template: string[]) => {
  return template.length === 0 ? [...previewDefaultTemplate] : [...template];
};

export const previewOptions = (yargs: CommonYargsArgv) =>
  buildOptions(yargs)
    .option("host", {
      type: "string",
      default: "127.0.0.1",
      describe: "Host used by the generated project production preview server",
    })
    .option("port", {
      type: "number",
      default: 5173,
      describe: "Port used by the generated project production preview server",
    })
    .option("image-domain", {
      type: "string",
      array: true,
      describe:
        "External image hostname allowed by the generated preview optimizer; repeat for multiple hosts",
    })
    .option("generate", {
      type: "boolean",
      default: true,
      describe:
        "Regenerate project files from .webstudio/data.json before building and starting preview",
    })
    .option("source", {
      type: "string",
      choices: previewSources,
      default: "local" satisfies PreviewSource,
      describe:
        "Project data source for generation: local uses .webstudio/data.json; session materializes the current ProjectSession snapshot first",
    })
    .example(
      "webstudio preview --port 5173",
      "Regenerate React Router app files, build them, and start the generated site at http://127.0.0.1:5173"
    )
    .example(
      "webstudio preview --template react-router --port 5173",
      "Regenerate files, build them, and start the generated site at http://127.0.0.1:5173"
    )
    .example(
      "webstudio preview --template react-router --generate false",
      "Build and start an already generated React Router app without rewriting project files"
    )
    .epilogue(
      [
        "Preview builds the generated app and starts its production server.",
        "Preview dependencies are isolated under .webstudio/preview and reused across regenerations.",
        "Do not add generated-preview dependencies to the repository root package.json or pnpm-lock.yaml.",
        "When launcher metadata is available, Preview reuses a supported npm or pnpm launcher. Without launcher metadata, it uses npm when available and otherwise falls back to pnpm.",
        "Unless npm_config_cache is already configured, npm uses a writable cache inside .webstudio/preview.",
        "For npm cache permission errors, unset npm_config_cache to use the preview-local cache, then retry.",
        "If dependency installation fails, check the reported package-manager path and network configuration, then reinstall or update the Webstudio CLI if the problem persists.",
      ].join("\n")
    );

type PreviewOptions = StrictYargsOptionsToInterface<typeof previewOptions>;

const isPositivePort = (value: number) =>
  Number.isInteger(value) && value > 0 && value <= 65535;

export const validatePreviewServerOptions = ({
  host,
  port,
  imageDomains,
}: {
  host: string;
  port: number;
  imageDomains?: string[];
}) => {
  if (host.length === 0) {
    throw new Error("--host must not be empty.");
  }
  if (isPositivePort(port) === false) {
    throw new Error("--port must be an integer between 1 and 65535.");
  }
  if (
    imageDomains?.some(
      (domain) => /^[a-z0-9.-]+(?::\d+)?$/i.test(domain) === false
    )
  ) {
    throw new Error(
      "Image domains must be hostnames without a protocol or path."
    );
  }
};

const createSilentSpinner = () => ({
  start: () => undefined,
  message: () => undefined,
  stop: () => undefined,
});

const localPreviewFiles = [
  LOCAL_CONFIG_FILE,
  LOCAL_DATA_FILE,
  ".webstudio/auth.json",
];

export const getNodeModulesSearchPaths = (moduleUrl: string) =>
  createRequire(moduleUrl).resolve.paths("webstudio-preview") ?? [];

const cliNodeModulesCandidates = getNodeModulesSearchPaths(import.meta.url);
const execFileAsync = promisify(execFile);
const dependencyMarker = ".webstudio-preview-dependencies";
const developmentCliVersion = "0.0.0-webstudio-version";
const previewDependencyInstallTimeout = 2 * 60_000;
type PreviewDependencyOperations = {
  access: (path: string) => Promise<void>;
  execFile: (
    file: string,
    args: string[],
    options: {
      cwd: string;
      env: NodeJS.ProcessEnv;
      timeout: number;
    }
  ) => Promise<unknown>;
  lstat: (path: string) => Promise<{ isSymbolicLink: () => boolean }>;
  readFile: (path: string, encoding: "utf8") => Promise<string>;
  readPackageFile?: (path: string) => string;
  resolveLauncherPath?: (path: string) => string;
  which?: (command: "npm" | "pnpm") => string | undefined;
  rm: (
    path: string,
    options: { recursive: true; force: true }
  ) => Promise<void>;
  symlink: (
    target: string,
    path: string,
    type: "dir" | "junction"
  ) => Promise<void>;
  writeFile: (path: string, data: string) => Promise<void>;
  nodeExecPath: string;
  npmExecPath?: string;
  platform: NodeJS.Platform;
  env: NodeJS.ProcessEnv;
};

const getPreviewInstallFailureDiagnostics = (error: unknown) => {
  if (typeof error !== "object" || error === null) {
    return sanitizeValidationDetail(String(error)).trim().slice(-2000);
  }
  const record = error as Record<string, unknown>;
  const output = [record.stderr, record.stdout, record.message].find(
    (value) => typeof value === "string" && value.trim().length > 0
  );
  const diagnostics = sanitizeValidationDetail(
    typeof output === "string" ? output : String(error)
  )
    .trim()
    .slice(-2000);
  const codeDiagnostics =
    typeof record.code === "number"
      ? `package-manager exit code ${record.code}. `
      : typeof record.code === "string"
        ? `package-manager process error ${record.code}. `
        : "";
  return `${codeDiagnostics}${diagnostics}`;
};

class PreviewDependencyInstallError extends Error {
  readonly code = "PREVIEW_DEPENDENCY_INSTALL_FAILED";
}

export const getPreviewProjectDir = (projectDir = cwd()) =>
  join(projectDir, ".webstudio", "preview");

type PreviewProcessOwner = {
  supervisorPid?: unknown;
  previewPid?: unknown;
};

export class PreviewCleanupError extends Error {
  readonly code = "PREVIEW_CLEANUP_FAILED";
}

export const createPreviewCleanupError = async ({
  previewProjectDir,
  lockedPath,
  cause,
  readOwnerFile = readFile,
}: {
  previewProjectDir: string;
  lockedPath: string;
  cause: unknown;
  readOwnerFile?: (path: string, encoding: "utf8") => Promise<string>;
}) => {
  const owner = await readOwnerFile(
    join(previewProjectDir, "..", previewProcessOwnerFile),
    "utf8"
  )
    .then((value) => JSON.parse(value) as PreviewProcessOwner)
    .catch(() => undefined);
  const pids = [owner?.supervisorPid, owner?.previewPid].filter(
    (value): value is number =>
      typeof value === "number" && Number.isInteger(value) && value > 0
  );
  const ownerHint =
    pids.length === 0
      ? "No owned preview PID was recorded."
      : `Recorded owned preview PIDs: ${pids.join(", ")}.`;
  const recovery =
    pids.length === 0
      ? "Stop the CLI/MCP process that started preview. On WSL/Windows, use PowerShell Get-CimInstance Win32_Process to find a command whose path is inside the locked preview directory, verify it belongs to this project, and stop only that PID."
      : `Stop preview from its owning CLI/MCP session. If that owner is gone, verify the recorded PID belongs to this project, then terminate only its tree (WSL/Windows: taskkill.exe /pid ${pids.at(-1)} /t /f; Linux/macOS: kill -- -${pids.at(-1)}).`;
  return new PreviewCleanupError(
    `PREVIEW_CLEANUP_FAILED: Could not remove generated preview path ${lockedPath}. A preview process may still have it open. ${ownerHint} ${recovery}`,
    { cause }
  );
};

export const ensurePreviewDependencies = async (
  previewProjectDir: string,
  dependencies: Partial<PreviewDependencyOperations> = {}
) => {
  const operations: PreviewDependencyOperations = {
    access,
    execFile: execFileAsync,
    lstat,
    readFile,
    rm,
    symlink,
    writeFile,
    nodeExecPath: process.execPath,
    npmExecPath: process.env.npm_execpath,
    platform: process.platform,
    env: process.env,
    ...dependencies,
  };
  const previewNodeModules = join(previewProjectDir, "node_modules");
  const packageJson = JSON.parse(
    await operations.readFile(join(previewProjectDir, "package.json"), "utf8")
  ) as {
    dependencies?: Record<string, string>;
    devDependencies?: Record<string, string>;
  };
  const requiredDependencies = {
    ...packageJson.dependencies,
    ...packageJson.devDependencies,
  };
  const usesDevelopmentDependencies = Object.values(
    requiredDependencies
  ).includes(developmentCliVersion);
  const manifestHash = createHash("sha256")
    .update(JSON.stringify(requiredDependencies))
    .digest("hex");
  const hasRequiredDependencies = async (nodeModules: string) => {
    try {
      await Promise.all(
        Object.keys(requiredDependencies).map((name) =>
          operations.access(join(nodeModules, name, "package.json"))
        )
      );
      return true;
    } catch {
      return false;
    }
  };

  try {
    const previewNodeModulesStat = await operations.lstat(previewNodeModules);
    if (
      previewNodeModulesStat.isSymbolicLink() &&
      usesDevelopmentDependencies &&
      (await hasRequiredDependencies(previewNodeModules))
    ) {
      return;
    }
    if (previewNodeModulesStat.isSymbolicLink() === false) {
      const installedHash = await operations
        .readFile(join(previewNodeModules, dependencyMarker), "utf8")
        .catch(() => "");
      if (
        installedHash === manifestHash &&
        (await hasRequiredDependencies(previewNodeModules))
      ) {
        return;
      }
    }
    try {
      await operations.rm(previewNodeModules, { recursive: true, force: true });
    } catch (error) {
      throw await createPreviewCleanupError({
        previewProjectDir,
        lockedPath: previewNodeModules,
        cause: error,
        readOwnerFile: operations.readFile,
      });
    }
  } catch (error) {
    if (error instanceof PreviewCleanupError) {
      throw error;
    }
    // Continue with the CLI dependency tree or an isolated install.
  }

  if (usesDevelopmentDependencies) {
    for (const cliNodeModules of cliNodeModulesCandidates) {
      if (await hasRequiredDependencies(cliNodeModules)) {
        // React Router scripts invoke package binaries through Node: pnpm's .bin
        // wrappers use paths relative to the original installation and cannot
        // be relocated through this directory link.
        await operations.symlink(
          cliNodeModules,
          previewNodeModules,
          operations.platform === "win32" ? "junction" : "dir"
        );
        return;
      }
    }
  }

  const packageManager = resolvePreviewPackageManager(operations);
  const installArgs =
    packageManager.name === "pnpm"
      ? ["install", "--no-lockfile", "--loglevel=error", "--ignore-workspace"]
      : [
          "install",
          "--legacy-peer-deps",
          "--no-audit",
          "--no-fund",
          "--package-lock=false",
          "--loglevel=error",
          "--workspaces=false",
        ];
  const invocation = {
    command: packageManager.command,
    args: [...packageManager.argsPrefix, ...installArgs],
  };
  const packageManagerPath =
    invocation.command === operations.nodeExecPath
      ? invocation.args[0]
      : invocation.command;
  const runtimeEnv = getNodeRuntimeEnv(
    operations.nodeExecPath,
    operations.env,
    operations.platform
  );
  const installEnv =
    packageManager.name === "npm" &&
    Object.keys(runtimeEnv).every(
      (name) => name.toLowerCase() !== "npm_config_cache"
    )
      ? {
          ...runtimeEnv,
          npm_config_cache: join(previewProjectDir, ".npm-cache"),
        }
      : runtimeEnv;

  try {
    await operations.execFile(invocation.command, invocation.args, {
      cwd: previewProjectDir,
      env: installEnv,
      timeout: previewDependencyInstallTimeout,
    });
  } catch (error) {
    throw new PreviewDependencyInstallError(
      `PREVIEW_DEPENDENCY_INSTALL_FAILED: Could not install the generated preview dependencies with ${packageManager.name} at ${packageManagerPath}. For npm cache permission errors, unset npm_config_cache to use the preview-local cache, then retry. Check the package-manager/network configuration, then reinstall or update webstudio if the problem persists.\n\nPackage-manager diagnostics:\n${getPreviewInstallFailureDiagnostics(error)}`,
      { cause: error }
    );
  }
  if ((await hasRequiredDependencies(previewNodeModules)) === false) {
    throw new Error(
      `PREVIEW_DEPENDENCIES_MISSING: ${packageManager.name} completed without installing every dependency declared by the generated preview. Reinstall or update webstudio, then retry.`
    );
  }
  await operations.writeFile(
    join(previewNodeModules, dependencyMarker),
    manifestHash
  );
};

const runInDirectory = async <Result>(
  directory: string,
  callback: () => Promise<Result>
) => {
  const previousDirectory = cwd();
  chdir(directory);
  try {
    return await callback();
  } finally {
    chdir(previousDirectory);
  }
};

const runExclusive = createExclusiveAsyncRunner();

const copyPreviewProjectFiles = async (
  projectDir: string,
  previewProjectDir: string
) => {
  await mkdir(join(previewProjectDir, ".webstudio"), { recursive: true });
  for (const file of localPreviewFiles) {
    await copyFile(join(projectDir, file), join(previewProjectDir, file)).catch(
      (error) => {
        if (
          error instanceof Error &&
          "code" in error &&
          error.code === "ENOENT"
        ) {
          return;
        }
        throw error;
      }
    );
  }
};

const hasIncrementalGenerationInputs = async (previewProjectDir: string) => {
  return await Promise.all([
    access(join(previewProjectDir, "app", "route-templates")),
    access(join(previewProjectDir, generatedFilesManifest)),
  ]).then(
    () => true,
    () => false
  );
};

const preparePreviewDirectory = async (
  projectDir: string,
  preserveGeneratedProject: boolean
) => {
  const previewProjectDir = getPreviewProjectDir(projectDir);
  await mkdir(previewProjectDir, { recursive: true });
  if (preserveGeneratedProject === false) {
    const entries = await readdir(previewProjectDir);
    await Promise.all(
      entries
        .filter((entry) => entry !== "node_modules")
        .map(async (entry) => {
          const entryPath = join(previewProjectDir, entry);
          try {
            await rm(entryPath, { recursive: true, force: true });
          } catch (error) {
            throw await createPreviewCleanupError({
              previewProjectDir,
              lockedPath: entryPath,
              cause: error,
            });
          }
        })
    );
  }
  await copyPreviewProjectFiles(projectDir, previewProjectDir);
  return previewProjectDir;
};

const getAssetFileMetadata = async (
  directory: string,
  relativeDirectory = ""
): Promise<string[]> => {
  const entries = await readdir(join(directory, relativeDirectory), {
    withFileTypes: true,
  }).catch(() => []);
  const metadata: string[] = [];
  for (const entry of entries.sort((left, right) =>
    left.name.localeCompare(right.name)
  )) {
    const relativePath = join(relativeDirectory, entry.name);
    if (entry.isDirectory()) {
      metadata.push(...(await getAssetFileMetadata(directory, relativePath)));
      continue;
    }
    if (entry.isFile()) {
      const file = await stat(join(directory, relativePath));
      metadata.push(`${relativePath}:${file.size}:${file.mtimeMs}`);
    }
  }
  return metadata;
};

export const getPreviewBuildCacheKey = async ({
  projectDir,
  assets,
  template,
  includeDraftPages = false,
  cliVersion = packageJson.version,
}: {
  projectDir: string;
  assets: boolean;
  template: string[];
  includeDraftPages?: boolean;
  cliVersion?: string;
}) => {
  if (cliVersion === developmentCliVersion) {
    return;
  }
  const hash = createHash("sha256");
  hash.update(
    JSON.stringify({
      version: 1,
      cliVersion,
      assets,
      template: getPreviewTemplates(template),
      includeDraftPages,
    })
  );
  for (const file of localPreviewFiles) {
    hash.update(file);
    hash.update(
      await readFile(join(projectDir, file), "utf8").catch(() => "<missing>")
    );
  }
  if (assets) {
    hash.update(
      JSON.stringify(
        await getAssetFileMetadata(join(projectDir, LOCAL_ASSETS_DIR))
      )
    );
  }
  return hash.digest("hex");
};

export const preparePreviewProject = async ({
  assets,
  template,
  generate,
  source = "local",
  syncIfMissing = false,
  syncDependencies = defaultSyncDependencies,
  accessLocalDataFile = access,
  prebuildProject = prebuild,
  ensureDependencies = ensurePreviewDependencies,
  getBuildCacheKey = getPreviewBuildCacheKey,
  silent = false,
  includeDraftPages = false,
  preserveGeneratedProject = false,
  prepareForIncrementalGeneration = false,
  reportProgress,
  prepareSessionDataFile = async () => {
    const connection = await resolveApiConnection();
    const session = createCliProjectSession({ connection });
    await session.initialize();
    await writeCliProjectSessionPreviewDataFile({
      session,
      connection,
      assetsDirectory: join(cwd(), LOCAL_ASSETS_DIR),
    });
  },
}: {
  assets: boolean;
  template: string[];
  generate: boolean;
  source?: PreviewSource;
  syncIfMissing?: boolean;
  syncDependencies?: SyncDependencies;
  accessLocalDataFile?: typeof access;
  prebuildProject?: typeof prebuild;
  ensureDependencies?: typeof ensurePreviewDependencies;
  getBuildCacheKey?: typeof getPreviewBuildCacheKey;
  silent?: boolean;
  includeDraftPages?: boolean;
  preserveGeneratedProject?: boolean;
  prepareForIncrementalGeneration?: boolean;
  reportProgress?: (message: string) => void;
  prepareSessionDataFile?: () => Promise<void>;
}): Promise<{
  cwd: string;
  buildCacheKey?: string;
  buildRequired?: boolean;
}> => {
  const projectDir = cwd();
  if (source === "session") {
    reportProgress?.("materializing session project data");
    await prepareSessionDataFile();
  }
  try {
    await accessLocalDataFile(LOCAL_DATA_FILE);
  } catch (error: unknown) {
    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
      if (syncIfMissing) {
        await sync(
          {},
          {
            ...syncDependencies,
            spinner: createSilentSpinner,
          }
        );
      } else {
        log.error(
          "You need to link and sync a Webstudio project before previewing it. Run `webstudio link` and `webstudio sync` first."
        );
        throw new HandledCliError();
      }
    } else {
      throw error;
    }
  }

  const previewProjectDir = getPreviewProjectDir(projectDir);
  if (generate === false) {
    return { cwd: previewProjectDir };
  }
  const prepareDependencies = async () => {
    reportProgress?.(
      `checking or installing generated preview dependencies (${previewDependencyInstallTimeout / 60_000} minute timeout)`
    );
    await ensureDependencies(previewProjectDir);
    reportProgress?.("generated preview project is ready");
  };

  const buildCacheKey = await getBuildCacheKey({
    projectDir,
    assets,
    template,
    includeDraftPages,
  });
  const hasIncrementalInputs =
    await hasIncrementalGenerationInputs(previewProjectDir);
  const canReuseCachedProject =
    prepareForIncrementalGeneration === false || hasIncrementalInputs;
  if (buildCacheKey !== undefined) {
    const cachedBuildKey = await readFile(
      join(previewProjectDir, previewBuildCacheMarker),
      "utf8"
    ).catch(() => undefined);
    if (cachedBuildKey === buildCacheKey && canReuseCachedProject) {
      await prepareDependencies();
      return { cwd: previewProjectDir, buildCacheKey, buildRequired: false };
    }
  }

  await runExclusive(async () => {
    const reuseGeneratedProject =
      preserveGeneratedProject && hasIncrementalInputs;
    await preparePreviewDirectory(projectDir, reuseGeneratedProject);
    await runInDirectory(previewProjectDir, async () => {
      reportProgress?.("generating preview files");
      await prebuildProject({
        assets,
        template: getPreviewTemplates(template),
        previewIdentity: true,
        sourceAssetsDirectory: join(projectDir, LOCAL_ASSETS_DIR),
        ...(silent ? { silent: true } : {}),
        ...(includeDraftPages ? { includeDraftPages: true } : {}),
        ...(reuseGeneratedProject ? { incremental: true } : {}),
        ...(prepareForIncrementalGeneration
          ? { preserveRouteTemplates: true }
          : {}),
      });
    });
    await prepareDependencies();
  });

  return {
    cwd: previewProjectDir,
    buildRequired: true,
    ...(buildCacheKey === undefined ? {} : { buildCacheKey }),
  };
};

export const buildPreparedPreview = async (
  previewProject: {
    cwd: string;
    buildCacheKey?: string;
    buildRequired?: boolean;
  },
  dependencies = { runPreviewBuild, writeFile }
) => {
  if (previewProject.buildRequired === false) {
    return false;
  }
  await dependencies.runPreviewBuild(undefined, previewProject.cwd);
  if (previewProject.buildCacheKey !== undefined) {
    await dependencies.writeFile(
      join(previewProject.cwd, previewBuildCacheMarker),
      previewProject.buildCacheKey
    );
  }
  return true;
};

export const preview = async (options: PreviewOptions) => {
  validatePreviewServerOptions({
    ...options,
    imageDomains: options.imageDomain,
  });
  const previewProject = await preparePreviewProject({
    assets: options.assets,
    template: options.template,
    generate: options.generate,
    source: options.source as PreviewSource,
  });

  const url = getPreviewUrl({ host: options.host, port: options.port });
  log.success(`Preview production server starting at ${url}`);
  await buildPreparedPreview(previewProject);
  const server = startPreviewServer({
    host: options.host,
    port: options.port,
    cwd: previewProject.cwd,
    imageDomains: options.imageDomain,
  });
  await waitForPreviewExit(server.process);
};