improve jsdoc and consolidate to single steup cli func

Author: james-elicx

packages/cloudflare/src/cli/commands/build.ts

@@ -1,26 +1,35 @@
-import { compileOpenNextConfig } from "@opennextjs/aws/build/compileConfig.js";
 import type yargs from "yargs";
 
 import { build as buildImpl } from "../build/build.js";
-import { createOpenNextConfigIfNotExistent } from "../build/utils/create-config-files.js";
 import type { WithWranglerArgs } from "./setup-cli.js";
 import { setupCLI, withWranglerOptions, withWranglerPassthroughArgs } from "./setup-cli.js";
 
+/**
+ * Implementation of the `opennextjs-clouflare build` command.
+ *
+ * @param args
+ */
 async function buildCommand(
 	args: WithWranglerArgs<{
 		skipNextBuild: boolean;
 		noMinify: boolean;
 		skipWranglerConfigCheck: boolean;
 	}>
-) {
-	const { options, config, wranglerConfig, baseDir } = await setupCLI("build", args, async (baseDir) => {
-		await createOpenNextConfigIfNotExistent(baseDir);
-		return compileOpenNextConfig(baseDir, undefined, { compileEdge: true });
+): Promise<void> {
+	const { options, config, wranglerConfig, baseDir } = await setupCLI({
+		command: "build",
+		shouldCompileConfig: true,
+		args,
 	});
 
-	return buildImpl(options, config, { ...args, minify: !args.noMinify, sourceDir: baseDir }, wranglerConfig);
+	await buildImpl(options, config, { ...args, minify: !args.noMinify, sourceDir: baseDir }, wranglerConfig);
 }
 
+/**
+ * Add the `build` command to yargs configuration.
+ *
+ * Consumes 1 positional parameter.
+ */
 export function addBuildCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
 		"build",

packages/cloudflare/src/cli/commands/deploy.ts

@@ -5,11 +5,16 @@ import { runWrangler } from "../utils/run-wrangler.js";
 import { getEnvFromPlatformProxy, quoteShellMeta } from "./helpers.js";
 import { populateCache, withPopulateCacheOptions } from "./populate-cache.js";
 import type { WithWranglerArgs } from "./setup-cli.js";
-import { setupCompiledAppCLI, withWranglerPassthroughArgs } from "./setup-cli.js";
+import { setupCLI, withWranglerPassthroughArgs } from "./setup-cli.js";
 import { getDeploymentMapping } from "./skew-protection.js";
 
-export async function deployCommand(args: WithWranglerArgs<{ cacheChunkSize: number }>) {
-	const { options, config, wranglerConfig } = await setupCompiledAppCLI("deploy", args);
+/**
+ * Implementation of the `opennextjs-clouflare deploy` command.
+ *
+ * @param args
+ */
+export async function deployCommand(args: WithWranglerArgs<{ cacheChunkSize: number }>): Promise<void> {
+	const { options, config, wranglerConfig } = await setupCLI({ command: "deploy", args });
 
 	const envVars = await getEnvFromPlatformProxy({
 		configPath: args.configPath,
@@ -40,6 +45,11 @@ export async function deployCommand(args: WithWranglerArgs<{ cacheChunkSize: num
 	);
 }
 
+/**
+ * Add the `deploy` command to yargs configuration.
+ *
+ * Consumes 1 positional parameter.
+ */
 export function addDeployCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
 		"deploy",

packages/cloudflare/src/cli/commands/populate-cache.ts

@@ -39,7 +39,7 @@ import type { WranglerTarget } from "../utils/run-wrangler.js";
 import { runWrangler } from "../utils/run-wrangler.js";
 import { getEnvFromPlatformProxy, quoteShellMeta } from "./helpers.js";
 import type { WithWranglerArgs } from "./setup-cli.js";
-import { setupCompiledAppCLI, withWranglerOptions, withWranglerPassthroughArgs } from "./setup-cli.js";
+import { setupCLI, withWranglerOptions, withWranglerPassthroughArgs } from "./setup-cli.js";
 
 async function resolveCacheName(
 	value:
@@ -275,11 +275,16 @@ export async function populateCache(
 	}
 }
 
-export async function populateCacheCommand(
+/**
+ * Implementation of the `opennextjs-clouflare populateCache` command.
+ *
+ * @param args
+ */
+async function populateCacheCommand(
 	target: "local" | "remote",
 	args: WithWranglerArgs<{ cacheChunkSize: number }>
 ) {
-	const { options, config, wranglerConfig } = await setupCompiledAppCLI("populate cache", args);
+	const { options, config, wranglerConfig } = await setupCLI({ command: "populate cache", args });
 
 	await populateCache(options, config, wranglerConfig, {
 		target,
@@ -289,6 +294,11 @@ export async function populateCacheCommand(
 	});
 }
 
+/**
+ * Add the `populateCache` command to yargs configuration, with nested commands for `local` and `remote`.
+ *
+ * Consumes 2 positional parameters.
+ */
 export function addPopulateCacheCommand<T extends yargs.Argv>(y: T) {
 	return y.command("populateCache", "Populate the cache for a built Next.js app", (c) =>
 		c

packages/cloudflare/src/cli/commands/preview.ts

@@ -3,10 +3,15 @@ import type yargs from "yargs";
 import { runWrangler } from "../utils/run-wrangler.js";
 import { populateCache, withPopulateCacheOptions } from "./populate-cache.js";
 import type { WithWranglerArgs } from "./setup-cli.js";
-import { setupCompiledAppCLI, withWranglerPassthroughArgs } from "./setup-cli.js";
+import { setupCLI, withWranglerPassthroughArgs } from "./setup-cli.js";
 
-export async function previewCommand(args: WithWranglerArgs<{ cacheChunkSize: number }>) {
-	const { options, config, wranglerConfig } = await setupCompiledAppCLI("preview", args);
+/**
+ * Implementation of the `opennextjs-clouflare preview` command.
+ *
+ * @param args
+ */
+export async function previewCommand(args: WithWranglerArgs<{ cacheChunkSize: number }>): Promise<void> {
+	const { options, config, wranglerConfig } = await setupCLI({ command: "preview", args });
 
 	await populateCache(options, config, wranglerConfig, {
 		target: "local",
@@ -18,6 +23,11 @@ export async function previewCommand(args: WithWranglerArgs<{ cacheChunkSize: nu
 	runWrangler(options, ["dev", ...args.wranglerArgs], { logging: "all" });
 }
 
+/**
+ * Add the `preview` command to yargs configuration.
+ *
+ * Consumes 1 positional parameter.
+ */
 export function addPreviewCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
 		"preview",

packages/cloudflare/src/cli/commands/setup-cli.ts

@@ -2,36 +2,44 @@ import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
+import { compileOpenNextConfig } from "@opennextjs/aws/build/compileConfig.js";
 import { normalizeOptions } from "@opennextjs/aws/build/helper.js";
 import { printHeader, showWarningOnWindows } from "@opennextjs/aws/build/utils.js";
 import logger from "@opennextjs/aws/logger.js";
 import { unstable_readConfig } from "wrangler";
 import type yargs from "yargs";
 
 import { OpenNextConfig } from "../../api/config.js";
-import { ensureCloudflareConfig } from "../build/utils/index.js";
+import { createOpenNextConfigIfNotExistent, ensureCloudflareConfig } from "../build/utils/index.js";
 
 export type WithWranglerArgs<T = unknown> = T & {
+	// Array of arguments that can be given to wrangler commands, including the `--config` and `--env` args.
 	wranglerArgs: string[];
 	configPath: string | undefined;
 	env: string | undefined;
 };
 
 const nextAppDir = process.cwd();
 
+type Options = {
+	command: string;
+	shouldCompileConfig?: boolean;
+	args: WithWranglerArgs;
+};
+
 /**
- * Setup the CLI, print necessary messages, and retrieve various options and configs.
+ * Sets up the CLI and returns config information:
+ * - Prints necessary header messages and warnings,
+ * - Retrieves the OpenNext config and validates it.
+ * - Initialises the OpenNext options.
+ * - Reads the Wrangler config.
  *
  * @param command
+ * @param shouldCompileConfig
  * @param args
- * @param getOpenNextConfig - Function that resolves to a config file
- * @returns CLI options, OpenNext config, and Wrangler config
+ * @returns CLI options, OpenNext config, and Wrangler config.
  */
-export async function setupCLI(
-	command: string,
-	args: WithWranglerArgs,
-	getOpenNextConfig: (baseDir: string) => Promise<{ config: OpenNextConfig; buildDir: string }>
-) {
+export async function setupCLI({ command, shouldCompileConfig, args }: Options) {
 	printHeader(`Cloudflare ${command}`);
 
 	showWarningOnWindows();
@@ -40,41 +48,44 @@ export async function setupCLI(
 	const require = createRequire(import.meta.url);
 	const openNextDistDir = path.dirname(require.resolve("@opennextjs/aws/index.js"));
 
-	const { config, buildDir } = await getOpenNextConfig(baseDir);
+	const { config, buildDir } = await getOpenNextConfig({ shouldCompileConfig, baseDir });
 	ensureCloudflareConfig(config);
 
 	// Initialize options
 	const options = normalizeOptions(config, openNextDistDir, buildDir);
 	logger.setLevel(options.debug ? "debug" : "info");
 
-	const wranglerConfig = unstable_readConfig({ env: args.env, config: args.config });
+	const wranglerConfig = unstable_readConfig({ env: args.env, config: args.configPath });
 
 	return { options, config, wranglerConfig, baseDir };
 }
 
-/**
- * Setup the CLI, print necessary messages, and resolve the compiled OpenNext config.
- *
- * @param command
- * @param args
- * @returns CLI config
- */
-export function setupCompiledAppCLI(command: string, args: WithWranglerArgs) {
-	return setupCLI(command, args, async (baseDir) => {
-		const configPath = path.join(baseDir, ".open-next/.build/open-next.config.edge.mjs");
+async function getOpenNextConfig(opts: {
+	shouldCompileConfig?: boolean;
+	baseDir: string;
+}): Promise<{ config: OpenNextConfig; buildDir: string }> {
+	if (opts.shouldCompileConfig) {
+		await createOpenNextConfigIfNotExistent(opts.baseDir);
+
+		return compileOpenNextConfig(opts.baseDir, undefined, { compileEdge: true });
+	}
 
-		if (!existsSync(configPath)) {
-			logger.error("Could not find compiled Open Next config");
-			process.exit(1);
-		}
+	const configPath = path.join(opts.baseDir, ".open-next/.build/open-next.config.edge.mjs");
 
-		const config = await import(configPath).then((mod) => mod.default);
+	if (!existsSync(configPath)) {
+		logger.error("Could not find compiled Open Next config");
+		process.exit(1);
+	}
 
-		// Note: buildDir is not used when an app is already compiled.
-		return { config, buildDir: baseDir };
-	});
+	const config = await import(configPath).then((mod) => mod.default);
+
+	// Note: buildDir is not used when an app is already compiled.
+	return { config, buildDir: opts.baseDir };
 }
 
+/**
+ * Add flags for the wrangler config path and environment to the yargs configuration.
+ */
 export function withWranglerOptions<T extends yargs.Argv>(args: T) {
 	return args
 		.options("configPath", {
@@ -89,6 +100,11 @@ export function withWranglerOptions<T extends yargs.Argv>(args: T) {
 		});
 }
 
+/**
+ *
+ * @param args
+ * @returns An array of arguments that can be given to wrangler commands, including the `--config` and `--env` args.
+ */
 function getWranglerArgs(args: {
 	_: (string | number)[];
 	configPath: string | undefined;
@@ -102,6 +118,11 @@ function getWranglerArgs(args: {
 	];
 }
 
+/**
+ *
+ * @param args
+ * @returns The inputted args, and an array of arguments that can be given to wrangler commands, including the `--config` and `--env` args.
+ */
 export function withWranglerPassthroughArgs<
 	T extends yargs.ArgumentsCamelCase<{
 		configPath: string | undefined;

packages/cloudflare/src/cli/commands/upload.ts

@@ -5,11 +5,16 @@ import { runWrangler } from "../utils/run-wrangler.js";
 import { getEnvFromPlatformProxy, quoteShellMeta } from "./helpers.js";
 import { populateCache, withPopulateCacheOptions } from "./populate-cache.js";
 import type { WithWranglerArgs } from "./setup-cli.js";
-import { setupCompiledAppCLI, withWranglerPassthroughArgs } from "./setup-cli.js";
+import { setupCLI, withWranglerPassthroughArgs } from "./setup-cli.js";
 import { getDeploymentMapping } from "./skew-protection.js";
 
-export async function uploadCommand(args: WithWranglerArgs<{ cacheChunkSize: number }>) {
-	const { options, config, wranglerConfig } = await setupCompiledAppCLI("upload", args);
+/**
+ * Implementation of the `opennextjs-clouflare upload` command.
+ *
+ * @param args
+ */
+export async function uploadCommand(args: WithWranglerArgs<{ cacheChunkSize: number }>): Promise<void> {
+	const { options, config, wranglerConfig } = await setupCLI({ command: "upload", args });
 
 	const envVars = await getEnvFromPlatformProxy({
 		configPath: args.configPath,
@@ -38,6 +43,11 @@ export async function uploadCommand(args: WithWranglerArgs<{ cacheChunkSize: num
 	);
 }
 
+/**
+ * Add the `upload` command to yargs configuration.
+ *
+ * Consumes 1 positional parameter.
+ */
 export function addUploadCommand<T extends yargs.Argv>(y: T) {
 	return y.command(
 		"upload",