[deploy-helpers] Extract Worker startup profiling from Wrangler

.changeset/bright-pandas-profile.md

@@ -0,0 +1,7 @@
+---
+"@cloudflare/deploy-helpers": minor
+---
+
+Share Worker startup profiling with other Cloudflare developer tools
+
+Move the bundle analyser out of Wrangler so `cf` and deploy failure diagnostics can use the same Miniflare CPU profiler. The `analyseBundle` callback on `DeployCallbacks` is now optional and deprecated, and will be removed in a future release once all clients have been updated to stop passing this property.

packages/deploy-helpers/package.json

@@ -29,6 +29,10 @@
 		"./create-worker-upload-form": {
 			"import": "./dist/create-worker-upload-form.mjs",
 			"types": "./dist/create-worker-upload-form.d.mts"
+		},
+		"./startup-profile": {
+			"import": "./dist/startup-profile.mjs",
+			"types": "./dist/startup-profile.d.mts"
 		}
 	},
 	"scripts": {
@@ -47,11 +51,13 @@
 		"blake3-wasm": "2.1.5",
 		"chalk": "catalog:default",
 		"command-exists": "catalog:default",
+		"devtools-protocol": "0.0.1182435",
 		"dotenv": "catalog:default",
 		"miniflare": "workspace:*",
 		"p-queue": "9.0.0",
 		"pretty-bytes": "6.1.1",
-		"undici": "catalog:default"
+		"undici": "catalog:default",
+		"ws": "catalog:default"
 	},
 	"devDependencies": {
 		"@cloudflare/workers-shared": "workspace:*",
@@ -60,8 +66,8 @@
 		"@types/command-exists": "^1.2.0",
 		"@types/json-diff": "^1.0.3",
 		"@types/node": "catalog:default",
+		"@types/ws": "^8.5.7",
 		"concurrently": "^8.2.2",
-		"devtools-protocol": "^0.0.1182435",
 		"esbuild": "catalog:default",
 		"json-diff": "^1.0.6",
 		"ts-dedent": "^2.2.0",

packages/deploy-helpers/scripts/deps.ts

@@ -11,6 +11,8 @@ export const EXTERNAL_DEPENDENCIES = [
 	"@cloudflare/containers-shared",
 	"@cloudflare/workers-utils",
 	"miniflare",
+	// Public declaration files expose Chrome DevTools Protocol profile types.
+	"devtools-protocol",
 
 	// These are externalized to avoid duplication in wrangler's bundle,
 	// which already bundles these packages itself.
@@ -21,4 +23,6 @@ export const EXTERNAL_DEPENDENCIES = [
 	"p-queue",
 	"pretty-bytes",
 	"undici",
+	// WebSocket client for the local workerd inspector used by startup profiling.
+	"ws",
 ];

packages/deploy-helpers/src/deploy/deploy.ts

@@ -126,9 +126,12 @@ export type DeployCallbacks = {
 				namespace: string | undefined;
 		  }>)
 		| undefined;
-	analyseBundle:
-		| ((workerBundle: string | FormData) => Promise<Record<string, unknown>>)
-		| undefined;
+	/**
+	 * @deprecated Startup profiling is provided by deploy-helpers automatically.
+	 */
+	analyseBundle?: (
+		workerBundle: string | FormData
+	) => Promise<Record<string, unknown>>;
 };
 
 type DeployResult = {
@@ -700,6 +703,7 @@ async function deployWorker(
 				dependencies,
 				workerBundle,
 				projectRoot,
+				// eslint-disable-next-line @typescript-eslint/no-deprecated -- compatibility callback for existing deploy-helpers consumers
 				callbacks.analyseBundle
 			);
 			if (message !== null) {

packages/deploy-helpers/src/deploy/helpers/friendly-validator-errors.ts

@@ -6,12 +6,14 @@ import { logger } from "../../shared/context";
 import type { Metafile } from "esbuild";
 import type { FormData } from "undici";
 
+type AnalyseBundle = (bundle: FormData | string) => Promise<unknown>;
+
 export async function helpIfErrorIsSizeOrScriptStartup(
 	err: unknown,
 	dependencies: { [path: string]: { bytesInOutput: number } },
 	workerBundle: FormData | string,
 	projectRoot: string | undefined,
-	analyseBundle?: (bundle: FormData | string) => Promise<unknown>
+	analyseBundle?: AnalyseBundle
 ): Promise<string | null> {
 	if (errIsScriptSize(err)) {
 		return diagnoseScriptSizeError(err, dependencies);
@@ -58,7 +60,7 @@ export async function diagnoseStartupError(
 	err: ParseError,
 	workerBundle: FormData | string,
 	projectRoot: string | undefined,
-	analyseBundle?: (bundle: FormData | string) => Promise<unknown>
+	analyseBundle: AnalyseBundle = analyseBundleLazily
 ): Promise<string> {
 	let errorMessage = dedent`
 		Your Worker failed validation because it exceeded startup limits.
@@ -71,24 +73,22 @@ export async function diagnoseStartupError(
 		Refer to https://developers.cloudflare.com/workers/platform/limits/#worker-startup-time for more details`;
 
 	try {
-		if (!analyseBundle) {
-			return errorMessage;
-		}
 		const cpuProfile = await analyseBundle(workerBundle);
 		const tmpDir = await getWranglerTmpDir(
 			projectRoot,
 			"startup-profile",
 			false
 		);
-		const profile = path.relative(
+		const profilePath = path.join(tmpDir.path, "worker.cpuprofile");
+		const displayProfilePath = path.relative(
 			projectRoot ?? process.cwd(),
-			path.join(tmpDir.path, `worker.cpuprofile`)
+			profilePath
 		);
-		await writeFile(profile, JSON.stringify(cpuProfile));
+		await writeFile(profilePath, JSON.stringify(cpuProfile));
 
 		errorMessage += dedent`
 
-			A CPU Profile of your Worker's startup phase has been written to ${profile} - load it into the Chrome DevTools profiler (or directly in VSCode) to view a flamegraph.`;
+			A CPU Profile of your Worker's startup phase has been written to ${displayProfilePath} - load it into the Chrome DevTools profiler (or directly in VSCode) to view a flamegraph.`;
 	} catch (profilingError) {
 		logger.debug(
 			`An error occurred while trying to locally profile the Worker: ${profilingError}`
@@ -98,6 +98,13 @@ export async function diagnoseStartupError(
 	return errorMessage;
 }
 
+async function analyseBundleLazily(
+	workerBundle: FormData | string
+): Promise<unknown> {
+	const { analyseBundle } = await import("../../startup-profile");
+	return analyseBundle(workerBundle);
+}
+
 /**
  * Gets a message that describes the largest dependencies in the script or `null` if there are none.
  */

packages/deploy-helpers/src/deploy/versions-upload.ts

@@ -70,6 +70,7 @@ import type { RetrieveSourceMapFunction } from "./helpers/sourcemap";
 import type { CfWorkerInit } from "@cloudflare/workers-utils";
 import type { FormData } from "undici";
 
+/** Compatibility callback shape for existing deploy-helpers consumers. */
 export type VersionsUploadCallbacks = Pick<DeployCallbacks, "analyseBundle">;
 
 type VersionsUploadResult = {
@@ -85,7 +86,7 @@ export default async function versionsUpload(
 	props: VersionsUploadProps,
 	config: ContainerlessConfig,
 	buildResult: WorkerBuildResult,
-	callbacks: VersionsUploadCallbacks
+	callbacks: VersionsUploadCallbacks = {}
 ): Promise<VersionsUploadResult> {
 	// DO NOT put anything in this function, this is just a thin wrapper to call writeOutput at the end
 
@@ -411,6 +412,7 @@ async function uploadWorkerVersion(
 				dependencies,
 				workerBundle,
 				projectRoot,
+				// eslint-disable-next-line @typescript-eslint/no-deprecated -- compatibility callback for existing deploy-helpers consumers
 				callbacks.analyseBundle
 			);
 			if (message) {