dev --once --debug-node-apis (#35201)

Flag to bundle non-'use node' entry points one at a time in order to provide an import trace if they use Node.js APIs.

If this works well it could run automatically on relevant bundler errors.

GitOrigin-RevId: bfbdc200f0f7a7246137671513f6b60e6858aee6

Author: thomasballinger

npm-packages/convex/src/bundler/debugBundle.ts

@@ -0,0 +1,248 @@
+import path from "path";
+import esbuild, { BuildFailure, LogLevel, Plugin } from "esbuild";
+import {
+  Context,
+  logError,
+  changeSpinner,
+  logFailure,
+  logVerbose,
+  logMessage,
+} from "./context.js";
+import { wasmPlugin } from "./wasm.js";
+import dependencyTrackerPlugin from "./depgraph.js";
+
+export async function innerEsbuild({
+  entryPoints,
+  platform,
+  dir,
+  extraConditions,
+  generateSourceMaps,
+  plugins,
+  chunksFolder,
+  logLevel,
+}: {
+  entryPoints: string[];
+  platform: esbuild.Platform;
+  dir: string;
+  extraConditions: string[];
+  generateSourceMaps: boolean;
+  plugins: Plugin[];
+  chunksFolder: string;
+  logLevel?: LogLevel;
+}) {
+  const result = await esbuild.build({
+    entryPoints,
+    bundle: true,
+    platform: platform,
+    format: "esm",
+    target: "esnext",
+    jsx: "automatic",
+    outdir: "out",
+    outbase: dir,
+    conditions: ["convex", "module", ...extraConditions],
+    plugins,
+    write: false,
+    sourcemap: generateSourceMaps,
+    splitting: true,
+    chunkNames: path.join(chunksFolder, "[hash]"),
+    treeShaking: true,
+    minifySyntax: true,
+    minifyIdentifiers: true,
+    // Enabling minifyWhitespace breaks sourcemaps on convex backends.
+    // The sourcemaps produced are valid on https://evanw.github.io/source-map-visualization
+    // but something we're doing (perhaps involving https://github.com/getsentry/rust-sourcemap)
+    // makes everything map to the same line.
+    minifyWhitespace: false, // false is the default, just showing for clarify.
+    keepNames: true,
+    define: {
+      "process.env.NODE_ENV": '"production"',
+    },
+    metafile: true,
+    logLevel: logLevel || "warning",
+  });
+  return result;
+}
+
+export function isEsbuildBuildError(e: any): e is BuildFailure {
+  return (
+    "errors" in e &&
+    "warnings" in e &&
+    Array.isArray(e.errors) &&
+    Array.isArray(e.warnings)
+  );
+}
+
+/**
+ * Bundle non-"use node" entry points one at a time to track down the first file with an error
+ * is being imported.
+ */
+export async function debugIsolateBundlesSerially(
+  ctx: Context,
+  {
+    entryPoints,
+    extraConditions,
+    dir,
+  }: {
+    entryPoints: string[];
+    extraConditions: string[];
+    dir: string;
+  },
+): Promise<void> {
+  logMessage(
+    ctx,
+    `Bundling convex entry points one at a time to track down things that can't be bundled for the Convex JS runtime.`,
+  );
+  let i = 1;
+  for (const entryPoint of entryPoints) {
+    changeSpinner(
+      ctx,
+      `bundling entry point ${entryPoint} (${i++}/${entryPoints.length})...`,
+    );
+
+    const { plugin, tracer } = dependencyTrackerPlugin();
+    try {
+      await innerEsbuild({
+        entryPoints: [entryPoint],
+        platform: "browser",
+        generateSourceMaps: true,
+        chunksFolder: "_deps",
+        extraConditions,
+        dir,
+        plugins: [plugin, wasmPlugin],
+        logLevel: "silent",
+      });
+    } catch (error) {
+      if (!isEsbuildBuildError(error) || !error.errors[0]) {
+        return await ctx.crash({
+          exitCode: 1,
+          errorType: "invalid filesystem data",
+          printedMessage: null,
+        });
+      }
+
+      const buildError = error.errors[0];
+      const errorFile = buildError.location?.file;
+      if (!errorFile) {
+        return await ctx.crash({
+          exitCode: 1,
+          errorType: "invalid filesystem data",
+          printedMessage: null,
+        });
+      }
+
+      const importedPath = buildError.text.match(/"([^"]+)"/)?.[1];
+      if (!importedPath) continue;
+
+      const full = path.resolve(errorFile);
+      logError(ctx, "");
+      logError(
+        ctx,
+        `Bundling ${entryPoint} resulted in ${error.errors.length} esbuild errors.`,
+      );
+      logError(
+        ctx,
+        `One of the bundling errors occurred while bundling ${full}:\n`,
+      );
+      logError(
+        ctx,
+        esbuild
+          .formatMessagesSync([buildError], {
+            kind: "error",
+            color: true,
+          })
+          .join("\n"),
+      );
+      logError(ctx, "It would help to avoid importing this file.");
+      const chains = tracer.traceImportChains(entryPoint, full);
+      const chain: string[] = chains[0];
+      chain.reverse();
+
+      logError(ctx, ``);
+      if (chain.length > 0) {
+        const problematicFileRelative = formatFilePath(dir, chain[0]);
+
+        if (chain.length === 1) {
+          logError(ctx, `  ${problematicFileRelative}`);
+        } else {
+          logError(ctx, `  ${problematicFileRelative} is imported by`);
+
+          for (let i = 1; i < chain.length - 1; i++) {
+            const fileRelative = formatFilePath(dir, chain[i]);
+            logError(ctx, `  ${fileRelative}, which is imported by`);
+          }
+
+          const entryPointFile = chain[chain.length - 1];
+          const entryPointRelative = formatFilePath(dir, entryPointFile);
+
+          logError(
+            ctx,
+            `  ${entryPointRelative}, which doesn't use "use node"\n`,
+          );
+          logError(
+            ctx,
+            `  For registered action functions to use Node.js APIs in any code they run they must be defined\n` +
+              `  in a file with 'use node' at the top. See https://docs.convex.dev/functions/runtimes#nodejs-runtime\n`,
+          );
+        }
+      }
+
+      logFailure(ctx, "Bundling failed");
+      return await ctx.crash({
+        exitCode: 1,
+        errorType: "invalid filesystem data",
+        printedMessage: "Bundling failed.",
+      });
+    }
+    logVerbose(ctx, `${entryPoint} bundled`);
+  }
+}
+
+// Helper function to format file paths consistently
+function formatFilePath(baseDir: string, filePath: string): string {
+  // If it's already a relative path like "./shared", just return it
+  if (!path.isAbsolute(filePath)) {
+    // For relative paths, ensure they start with "convex/"
+    if (!filePath.startsWith("convex/")) {
+      // If it's a path like "./subdir/file.ts" or "subdir/file.ts"
+      const cleanPath = filePath.replace(/^\.\//, "");
+      return `convex/${cleanPath}`;
+    }
+    return filePath;
+  }
+
+  // Get the path relative to the base directory
+  const relativePath = path.relative(baseDir, filePath);
+
+  // Remove any leading "./" that path.relative might add
+  const cleanPath = relativePath.replace(/^\.\//, "");
+
+  // Check if this is a path within the convex directory
+  const isConvexPath =
+    cleanPath.startsWith("convex/") ||
+    cleanPath.includes("/convex/") ||
+    path.dirname(cleanPath) === "convex";
+
+  if (isConvexPath) {
+    // If it already starts with convex/, return it as is
+    if (cleanPath.startsWith("convex/")) {
+      return cleanPath;
+    }
+
+    // For files in the convex directory
+    if (path.dirname(cleanPath) === "convex") {
+      const filename = path.basename(cleanPath);
+      return `convex/${filename}`;
+    }
+
+    // For files in subdirectories of convex
+    const convexIndex = cleanPath.indexOf("convex/");
+    if (convexIndex >= 0) {
+      return cleanPath.substring(convexIndex);
+    }
+  }
+
+  // For any other path, assume it's in the convex directory
+  // This handles cases where the file is in a subdirectory of convex
+  // but the path doesn't include "convex/" explicitly
+  return `convex/${cleanPath}`;
+}