@slidev-react/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 slidev-react contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# `@slidev-react/node`
+
+`@slidev-react/node` 提供 `slidev-react` 的 Node 侧命令 API。
+
+当前导出分两层：
+
+高层命令 API：
+
+- `runSlidesDev`
+- `runSlidesBuild`
+- `runSlidesExport`
+- `runSlidesLint`
+
+更底层的 programmatic API：
+
+- `startSlidesDevServer`
+- `buildSlidesApp`
+- `exportSlidesArtifacts`
+- `lintSlides`
+
+这一层的目标是把 CLI 和根仓库脚本解耦，同时把 slides authoring/build 生命周期沉到可复用的 Node 侧能力。

package/dist/build.d.mts

@@ -0,0 +1,10 @@
+import { CommandResult, SlidesCommandOptions } from "./context.mjs";
+
+//#region src/build.d.ts
+interface BuildSlidesOptions extends SlidesCommandOptions {
+  viteArgs?: string[];
+}
+declare function buildSlidesApp(options?: BuildSlidesOptions): Promise<void>;
+declare function runSlidesBuild(options?: BuildSlidesOptions): Promise<CommandResult>;
+//#endregion
+export { buildSlidesApp, runSlidesBuild };

package/dist/build.mjs

@@ -0,0 +1,28 @@
+import { createSuccessResult, resolveSlidesCommandContext } from "./context.mjs";
+import { parseBuildArgs } from "./cli/buildArgs.mjs";
+import { createSlidesViteConfig } from "./slides/build/createSlidesViteConfig.mjs";
+import { build, mergeConfig } from "vite";
+//#region src/build.ts
+async function buildSlidesApp(options = {}) {
+	const parsedArgs = parseBuildArgs(options.viteArgs ?? []);
+	await build(mergeConfig(createSlidesViteConfig(resolveSlidesCommandContext({
+		...options,
+		slidesFile: options.slidesFile ?? parsedArgs.slidesFile
+	})), {
+		configFile: false,
+		mode: parsedArgs.mode,
+		base: parsedArgs.base,
+		build: {
+			outDir: parsedArgs.outDir,
+			emptyOutDir: parsedArgs.emptyOutDir,
+			sourcemap: parsedArgs.sourcemap,
+			minify: parsedArgs.minify
+		}
+	}));
+}
+async function runSlidesBuild(options = {}) {
+	await buildSlidesApp(options);
+	return createSuccessResult();
+}
+//#endregion
+export { buildSlidesApp, runSlidesBuild };

package/dist/cli/buildArgs.mjs

@@ -0,0 +1,78 @@
+import { parseBooleanFlag } from "../context.mjs";
+import { readOptionValue } from "./readOptionValue.mjs";
+//#region src/cli/buildArgs.ts
+function parseBuildArgs(argv) {
+	let slidesFile;
+	let outDir;
+	let base;
+	let mode;
+	let emptyOutDir;
+	let sourcemap;
+	let minify;
+	for (let index = 0; index < argv.length; index += 1) {
+		const entry = argv[index];
+		if (!entry.startsWith("--")) {
+			if (!slidesFile) {
+				slidesFile = entry;
+				continue;
+			}
+			throw new Error(`Unknown build argument "${entry}".`);
+		}
+		if (entry === "--emptyOutDir") {
+			emptyOutDir = true;
+			continue;
+		}
+		if (entry === "--sourcemap") {
+			sourcemap = true;
+			continue;
+		}
+		if (entry === "--minify") {
+			minify = true;
+			continue;
+		}
+		if (entry === "--outDir" || entry.startsWith("--outDir=")) {
+			const result = readOptionValue(argv, index, "--outDir");
+			outDir = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--base" || entry.startsWith("--base=")) {
+			const result = readOptionValue(argv, index, "--base");
+			base = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--mode" || entry.startsWith("--mode=")) {
+			const result = readOptionValue(argv, index, "--mode");
+			mode = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry.startsWith("--emptyOutDir=")) {
+			emptyOutDir = parseBooleanFlag(entry.slice(14));
+			continue;
+		}
+		if (entry.startsWith("--sourcemap=")) {
+			const value = entry.slice(12);
+			sourcemap = value === "inline" || value === "hidden" ? value : parseBooleanFlag(value);
+			continue;
+		}
+		if (entry.startsWith("--minify=")) {
+			const value = entry.slice(9);
+			minify = value === "esbuild" || value === "terser" ? value : parseBooleanFlag(value);
+			continue;
+		}
+		throw new Error(`Unknown build option "${entry}".`);
+	}
+	return {
+		slidesFile,
+		outDir,
+		base,
+		mode,
+		emptyOutDir,
+		sourcemap,
+		minify
+	};
+}
+//#endregion
+export { parseBuildArgs };

package/dist/cli/devArgs.mjs

@@ -0,0 +1,74 @@
+import { parseBooleanFlag, parsePositiveIntegerOption } from "../context.mjs";
+import { readOptionValue } from "./readOptionValue.mjs";
+//#region src/cli/devArgs.ts
+function parseDevArgs(argv) {
+	let slidesFile;
+	let host;
+	let port;
+	let open;
+	let strictPort;
+	let base;
+	let mode;
+	for (let index = 0; index < argv.length; index += 1) {
+		const entry = argv[index];
+		if (!entry.startsWith("--")) {
+			if (!slidesFile) {
+				slidesFile = entry;
+				continue;
+			}
+			throw new Error(`Unknown dev argument "${entry}".`);
+		}
+		if (entry === "--open") {
+			open = true;
+			continue;
+		}
+		if (entry === "--strictPort") {
+			strictPort = true;
+			continue;
+		}
+		if (entry === "--host" || entry.startsWith("--host=")) {
+			const result = readOptionValue(argv, index, "--host");
+			host = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--port" || entry.startsWith("--port=")) {
+			const result = readOptionValue(argv, index, "--port");
+			port = parsePositiveIntegerOption("--port", result.value);
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--base" || entry.startsWith("--base=")) {
+			const result = readOptionValue(argv, index, "--base");
+			base = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--mode" || entry.startsWith("--mode=")) {
+			const result = readOptionValue(argv, index, "--mode");
+			mode = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--open=false" || entry === "--open=true") {
+			open = parseBooleanFlag(entry.slice(7));
+			continue;
+		}
+		if (entry === "--strictPort=false" || entry === "--strictPort=true") {
+			strictPort = parseBooleanFlag(entry.slice(13));
+			continue;
+		}
+		throw new Error(`Unknown dev option "${entry}".`);
+	}
+	return {
+		slidesFile,
+		host,
+		port,
+		open,
+		strictPort,
+		base,
+		mode
+	};
+}
+//#endregion
+export { parseDevArgs };

package/dist/cli/exportArgs.mjs

@@ -0,0 +1,87 @@
+import { parsePositiveIntegerOption } from "../context.mjs";
+import { readOptionValue } from "./readOptionValue.mjs";
+import { parseSlideSelection } from "@slidev-react/core/presentation/export/selection";
+//#region src/cli/exportArgs.ts
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 4173;
+const DEFAULT_OUTPUT_DIR = "output/export";
+function parseExportArgs(argv) {
+	let slidesFile;
+	let format = "all";
+	let host = DEFAULT_HOST;
+	let port = DEFAULT_PORT;
+	let baseUrl;
+	let withClicks = false;
+	let outputDir = DEFAULT_OUTPUT_DIR;
+	let slideSelection = parseSlideSelection(void 0);
+	for (let index = 0; index < argv.length; index += 1) {
+		const entry = argv[index];
+		if (!entry.startsWith("--")) {
+			if (!slidesFile) {
+				slidesFile = entry;
+				continue;
+			}
+			throw new Error(`Unknown export argument "${entry}".`);
+		}
+		if (entry === "--with-clicks") {
+			withClicks = true;
+			continue;
+		}
+		if (entry === "--file" || entry.startsWith("--file=")) {
+			const result = readOptionValue(argv, index, "--file");
+			slidesFile = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--format" || entry.startsWith("--format=")) {
+			const result = readOptionValue(argv, index, "--format");
+			if (result.value === "pdf" || result.value === "png" || result.value === "all") format = result.value;
+			else throw new Error(`Unknown export format "${result.value}".`);
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--host" || entry.startsWith("--host=")) {
+			const result = readOptionValue(argv, index, "--host");
+			host = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--port" || entry.startsWith("--port=")) {
+			const result = readOptionValue(argv, index, "--port");
+			port = parsePositiveIntegerOption("--port", result.value);
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--base-url" || entry.startsWith("--base-url=")) {
+			const result = readOptionValue(argv, index, "--base-url");
+			baseUrl = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--output" || entry.startsWith("--output=")) {
+			const result = readOptionValue(argv, index, "--output");
+			outputDir = result.value;
+			index = result.nextIndex;
+			continue;
+		}
+		if (entry === "--slides" || entry.startsWith("--slides=")) {
+			const result = readOptionValue(argv, index, "--slides");
+			slideSelection = parseSlideSelection(result.value);
+			index = result.nextIndex;
+			continue;
+		}
+		throw new Error(`Unknown export option "${entry}".`);
+	}
+	return {
+		slidesFile,
+		format,
+		host,
+		port,
+		baseUrl: baseUrl || `http://${host}:${port}`,
+		withClicks,
+		outputDir,
+		slideSelection
+	};
+}
+//#endregion
+export { parseExportArgs };

package/dist/cli/lintArgs.mjs

@@ -0,0 +1,32 @@
+//#region src/cli/lintArgs.ts
+function parseLintArgs(argv) {
+	let slidesFile;
+	let strict = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const entry = argv[index];
+		if (entry === "--strict") {
+			strict = true;
+			continue;
+		}
+		if (entry === "--file" && argv[index + 1]) {
+			slidesFile = argv[index + 1];
+			index += 1;
+			continue;
+		}
+		if (entry.startsWith("--file=")) {
+			slidesFile = entry.slice(7);
+			continue;
+		}
+		if (!entry.startsWith("--")) {
+			slidesFile = entry;
+			continue;
+		}
+		throw new Error(`Unknown lint option "${entry}".`);
+	}
+	return {
+		slidesFile,
+		strict
+	};
+}
+//#endregion
+export { parseLintArgs };

package/dist/cli/readOptionValue.mjs

@@ -0,0 +1,16 @@
+//#region src/cli/readOptionValue.ts
+function readOptionValue(argv, index, optionName) {
+	const current = argv[index];
+	if (current.startsWith(`${optionName}=`)) return {
+		value: current.slice(optionName.length + 1),
+		nextIndex: index
+	};
+	const nextValue = argv[index + 1];
+	if (!nextValue || nextValue.startsWith("--")) throw new Error(`Missing value for ${optionName}.`);
+	return {
+		value: nextValue,
+		nextIndex: index + 1
+	};
+}
+//#endregion
+export { readOptionValue };

package/dist/context.d.mts

@@ -0,0 +1,11 @@
+//#region src/context.d.ts
+interface CommandResult {
+  code: number;
+  signal: NodeJS.Signals | null;
+}
+interface SlidesCommandOptions {
+  appRoot?: string;
+  slidesFile?: string;
+}
+//#endregion
+export { CommandResult, SlidesCommandOptions };

package/dist/context.mjs

@@ -0,0 +1,37 @@
+import { resolveSlidesSourceFile } from "./slides/build/slidesSourceFile.mjs";
+import path from "node:path";
+//#region src/context.ts
+function createSuccessResult() {
+	return {
+		code: 0,
+		signal: null
+	};
+}
+function createFailureResult(code = 1) {
+	return {
+		code,
+		signal: null
+	};
+}
+function resolveSlidesCommandContext(options = {}) {
+	const appRoot = path.resolve(options.appRoot ?? process.cwd());
+	const slidesFile = options.slidesFile?.trim() || void 0;
+	return {
+		appRoot,
+		slidesFile,
+		slidesSourceFile: resolveSlidesSourceFile(appRoot, slidesFile)
+	};
+}
+function parseBooleanFlag(value, defaultValue = true) {
+	if (value == null || value === "") return defaultValue;
+	if (value === "true") return true;
+	if (value === "false") return false;
+	throw new Error(`Expected a boolean value, received "${value}".`);
+}
+function parsePositiveIntegerOption(name, value) {
+	const parsed = Number.parseInt(value, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`Expected ${name} to be a positive integer, received "${value}".`);
+	return parsed;
+}
+//#endregion
+export { createFailureResult, createSuccessResult, parseBooleanFlag, parsePositiveIntegerOption, resolveSlidesCommandContext };

package/dist/dev.d.mts

@@ -0,0 +1,13 @@
+import { CommandResult, SlidesCommandOptions } from "./context.mjs";
+import { ViteDevServer } from "vite";
+
+//#region src/dev.d.ts
+interface DevSlidesOptions extends SlidesCommandOptions {
+  viteArgs?: string[];
+  printUrls?: boolean;
+}
+declare function startSlidesDevServer(options?: DevSlidesOptions): Promise<ViteDevServer>;
+declare function runSlidesDev(options?: DevSlidesOptions): Promise<CommandResult>;
+declare function stopSlidesDevServer(server: ViteDevServer): Promise<void>;
+//#endregion
+export { runSlidesDev, startSlidesDevServer, stopSlidesDevServer };

package/dist/dev.mjs

@@ -0,0 +1,61 @@
+import { resolveSlidesCommandContext } from "./context.mjs";
+import { createSlidesViteConfig } from "./slides/build/createSlidesViteConfig.mjs";
+import { parseDevArgs } from "./cli/devArgs.mjs";
+import { createServer, mergeConfig } from "vite";
+//#region src/dev.ts
+async function startSlidesDevServer(options = {}) {
+	const parsedArgs = parseDevArgs(options.viteArgs ?? []);
+	const server = await createServer(mergeConfig(createSlidesViteConfig(resolveSlidesCommandContext({
+		...options,
+		slidesFile: options.slidesFile ?? parsedArgs.slidesFile
+	})), {
+		configFile: false,
+		clearScreen: false,
+		mode: parsedArgs.mode,
+		base: parsedArgs.base,
+		server: {
+			host: parsedArgs.host,
+			port: parsedArgs.port,
+			open: parsedArgs.open,
+			strictPort: parsedArgs.strictPort
+		}
+	}));
+	await server.listen();
+	if (options.printUrls !== false) server.printUrls();
+	return server;
+}
+function waitForServerShutdown(server) {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		const signalHandlers = /* @__PURE__ */ new Map();
+		const cleanup = async (signal) => {
+			if (settled) return;
+			settled = true;
+			for (const [eventName, handler] of signalHandlers) process.off(eventName, handler);
+			try {
+				await server.close();
+				resolve({
+					code: 0,
+					signal
+				});
+			} catch (error) {
+				reject(error);
+			}
+		};
+		for (const signal of ["SIGINT", "SIGTERM"]) {
+			const handler = () => {
+				cleanup(signal);
+			};
+			signalHandlers.set(signal, handler);
+			process.on(signal, handler);
+		}
+	});
+}
+async function runSlidesDev(options = {}) {
+	return waitForServerShutdown(await startSlidesDevServer(options));
+}
+async function stopSlidesDevServer(server) {
+	await server.close();
+}
+//#endregion
+export { runSlidesDev, startSlidesDevServer, stopSlidesDevServer };

package/dist/export.d.mts

@@ -0,0 +1,11 @@
+import { CommandResult, SlidesCommandOptions } from "./context.mjs";
+import { ExportSlidesArtifactsResult } from "./exportBrowser.mjs";
+
+//#region src/export.d.ts
+interface ExportSlidesOptions extends SlidesCommandOptions {
+  cliArgs?: string[];
+}
+declare function exportSlidesArtifacts(options?: ExportSlidesOptions): Promise<ExportSlidesArtifactsResult>;
+declare function runSlidesExport(options?: ExportSlidesOptions): Promise<CommandResult>;
+//#endregion
+export { exportSlidesArtifacts, runSlidesExport };

package/dist/export.mjs

@@ -0,0 +1,67 @@
+import { createSuccessResult } from "./context.mjs";
+import { parseExportArgs } from "./cli/exportArgs.mjs";
+import { startSlidesDevServer, stopSlidesDevServer } from "./dev.mjs";
+import { exportSlidesInBrowser } from "./exportBrowser.mjs";
+import { setTimeout } from "node:timers/promises";
+import { buildPrintExportUrl } from "@slidev-react/core/presentation/export/urls";
+//#region src/export.ts
+const DEV_SERVER_TIMEOUT_MS = 12e4;
+async function isServerReachable(baseUrl) {
+	try {
+		return (await fetch(baseUrl, { signal: AbortSignal.timeout(2e3) })).ok;
+	} catch {
+		return false;
+	}
+}
+async function waitForServer(baseUrl, timeoutMs) {
+	const startedAt = Date.now();
+	while (Date.now() - startedAt < timeoutMs) {
+		if (await isServerReachable(baseUrl)) return;
+		await setTimeout(500);
+	}
+	throw new Error(`Timed out waiting for ${baseUrl}`);
+}
+async function exportSlidesArtifacts(options = {}) {
+	const parsedArgs = parseExportArgs(options.cliArgs ?? []);
+	const exportOptions = {
+		...parsedArgs,
+		slidesFile: options.slidesFile ?? parsedArgs.slidesFile
+	};
+	const printUrl = buildPrintExportUrl(exportOptions.baseUrl, { withClicks: exportOptions.withClicks });
+	const devServer = await isServerReachable(exportOptions.baseUrl) ? null : await startSlidesDevServer({
+		appRoot: options.appRoot,
+		slidesFile: exportOptions.slidesFile,
+		printUrls: false,
+		viteArgs: [
+			"--host",
+			exportOptions.host,
+			"--port",
+			String(exportOptions.port)
+		]
+	});
+	if (devServer) await waitForServer(exportOptions.baseUrl, DEV_SERVER_TIMEOUT_MS);
+	try {
+		return await exportSlidesInBrowser({
+			printUrl,
+			format: exportOptions.format,
+			outputDir: exportOptions.outputDir,
+			withClicks: exportOptions.withClicks,
+			slideSelection: exportOptions.slideSelection
+		});
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (/Executable doesn't exist|browserType\.launch/i.test(message)) throw new Error(`${message}\nRun \`pnpm run test:e2e:install\` first so Playwright can install Chromium.`);
+		throw error;
+	} finally {
+		if (devServer) await stopSlidesDevServer(devServer);
+	}
+}
+async function runSlidesExport(options = {}) {
+	const result = await exportSlidesArtifacts(options);
+	console.log("[slide-react] export complete");
+	console.log(`  slides: ${result.selectedSlides.join(", ")}${result.variantLabel ? ` (${result.variantLabel})` : ""}`);
+	for (const file of result.createdFiles) console.log(`  - ${file}`);
+	return createSuccessResult();
+}
+//#endregion
+export { exportSlidesArtifacts, runSlidesExport };

package/dist/exportBrowser.d.mts

@@ -0,0 +1,8 @@
+//#region src/exportBrowser.d.ts
+interface ExportSlidesArtifactsResult {
+  createdFiles: string[];
+  selectedSlides: number[];
+  variantLabel: string;
+}
+//#endregion
+export { ExportSlidesArtifactsResult };