feat(cli): warn on createRequire packages missing from deployed images

Packages loaded via createRequire(import.meta.url)("pkg") are invisible
to the bundler: they are neither bundled nor installed into the deployed
image, and the deploy succeeds silently before failing at runtime with a
module-not-found error. Deploy builds now scan user source files for such
loads, cross-check against the packages actually installed in the image,
and warn with file and line, suggesting the additionalPackages build
extension. Deploys also surface the bundler's own warnings for user files
instead of discarding them.

Author: matt-aitken

.changeset/warn-createrequire-deploy.md

@@ -0,0 +1,5 @@
+---
+"trigger.dev": patch
+---
+
+Deploys now warn when a package is loaded with `createRequire()` but won't be available in the deployed image. The bundler can't follow `createRequire()` calls, so such a package is neither bundled nor installed, and previously this failed only at runtime with a confusing module-not-found error. The warning points at the exact file and line and suggests the `additionalPackages` build extension. Deploys also now surface the bundler's own warnings for your files (for example `require()` with a non-literal argument) instead of discarding them.

packages/cli-v3/src/build/buildWorker.ts

@@ -1,6 +1,13 @@
 import { ResolvedConfig } from "@trigger.dev/core/v3/build";
 import { BuildManifest, BuildTarget } from "@trigger.dev/core/v3/schemas";
-import { BundleResult, bundleWorker, createBuildManifestFromBundle } from "./bundle.js";
+import * as esbuild from "esbuild";
+import {
+  BundleResult,
+  bundleWorker,
+  createBuildManifestFromBundle,
+  logBuildWarnings,
+} from "./bundle.js";
+import { CreateRequireCollector, createRequireUsageToWarning } from "./createRequireWarnings.js";
 import { bundleSkills } from "./bundleSkills.js";
 import {
   createBuildContext,
@@ -72,6 +79,7 @@ export async function buildWorker(options: BuildWorkerOptions) {
   const pluginsFromExtensions = resolvePluginsForContext(buildContext);
 
   const sdkVersionExtractor = new SdkVersionExtractor();
+  const createRequireCollector = new CreateRequireCollector(resolvedConfig.workingDir);
 
   options.listener?.onBundleStart?.();
 
@@ -81,7 +89,11 @@ export async function buildWorker(options: BuildWorkerOptions) {
     destination: options.destination,
     watch: false,
     resolvedConfig,
-    plugins: [sdkVersionExtractor.plugin, ...pluginsFromExtensions],
+    plugins: [
+      sdkVersionExtractor.plugin,
+      ...(options.target === "dev" ? [] : [createRequireCollector.plugin]),
+      ...pluginsFromExtensions,
+    ],
     jsxFactory: resolvedConfig.build.jsx.factory,
     jsxFragment: resolvedConfig.build.jsx.fragment,
     jsxAutomatic: resolvedConfig.build.jsx.automatic,
@@ -127,6 +139,16 @@ export async function buildWorker(options: BuildWorkerOptions) {
   buildManifest = await notifyExtensionOnBuildComplete(buildContext, buildManifest);
 
   if (options.target !== "dev") {
+    const buildWarnings = collectDeployBuildWarnings(
+      bundleResult,
+      createRequireCollector,
+      buildManifest
+    );
+
+    if (buildWarnings.length > 0) {
+      logBuildWarnings(buildWarnings);
+    }
+
     buildManifest = options.rewritePaths
       ? rewriteBuildManifestPaths(buildManifest, options.destination)
       : buildManifest;
@@ -142,6 +164,31 @@ export async function buildWorker(options: BuildWorkerOptions) {
   return buildManifest;
 }
 
+/**
+ * Deploy-only diagnostics: esbuild's own warnings scoped to the user's files,
+ * plus packages loaded via createRequire() that end up neither bundled nor
+ * installed in the image (i.e. not in the manifest's externals).
+ */
+function collectDeployBuildWarnings(
+  bundleResult: BundleResult,
+  createRequireCollector: CreateRequireCollector,
+  buildManifest: BuildManifest
+): esbuild.PartialMessage[] {
+  const esbuildWarnings = bundleResult.warnings.filter(
+    (warning) => warning.location?.file && !warning.location.file.includes("node_modules")
+  );
+
+  const installedPackages = new Set(
+    (buildManifest.externals ?? []).map((external) => external.name)
+  );
+
+  const createRequireWarnings = createRequireCollector.usages
+    .filter((usage) => !installedPackages.has(usage.packageName))
+    .map(createRequireUsageToWarning);
+
+  return [...esbuildWarnings, ...createRequireWarnings];
+}
+
 /** @knipignore Exported for the CLI end-to-end suite. */
 export function rewriteBuildManifestPaths(
   buildManifest: BuildManifest,

packages/cli-v3/src/build/bundle.ts

@@ -55,6 +55,7 @@ export type BundleResult = {
   stop: (() => Promise<void>) | undefined;
   /** Maps output file paths to their content hashes for deduplication */
   outputHashes: Record<string, string>;
+  warnings: esbuild.Message[];
 };
 
 export class BundleError extends Error {
@@ -323,6 +324,7 @@ export async function getBundleResultFromBuild(
     contentHash: hasher.digest("hex"),
     metafile: result.metafile,
     outputHashes,
+    warnings: result.warnings,
   };
 }
 
@@ -340,7 +342,7 @@ function dirToEntryPointGlob(dir: string): string[] {
   ];
 }
 
-export function logBuildWarnings(warnings: esbuild.Message[]) {
+export function logBuildWarnings(warnings: esbuild.PartialMessage[]) {
   const logs = esbuild.formatMessagesSync(warnings, { kind: "warning", color: true });
   for (const log of logs) {
     console.warn(log);

packages/cli-v3/src/build/createRequireWarnings.test.ts

@@ -0,0 +1,198 @@
+import { build } from "esbuild";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  CreateRequireCollector,
+  packageNameForSpecifier,
+  scanSourceForCreateRequire,
+} from "./createRequireWarnings.js";
+
+describe("scanSourceForCreateRequire", () => {
+  it("finds a direct createRequire invocation with a string literal", () => {
+    const source = `import { createRequire } from "node:module";
+const mssql = createRequire(import.meta.url)("mssql");
+`;
+
+    const results = scanSourceForCreateRequire(source);
+
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({
+      specifier: "mssql",
+      line: 2,
+      column: 14,
+      lineText: `const mssql = createRequire(import.meta.url)("mssql");`,
+    });
+  });
+
+  it("finds calls through a variable assigned from createRequire", () => {
+    const source = `import { createRequire } from "module";
+const req = createRequire(import.meta.url);
+const pg = req("pg");
+const client = req('ioredis');
+`;
+
+    const results = scanSourceForCreateRequire(source);
+
+    expect(results.map((r) => r.specifier)).toEqual(["pg", "ioredis"]);
+    expect(results[0]).toMatchObject({ line: 3, column: 11 });
+  });
+
+  it("finds calls through require.resolve on the created require", () => {
+    const source = `import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+const path = req.resolve("sharp");
+`;
+
+    expect(scanSourceForCreateRequire(source).map((r) => r.specifier)).toEqual(["sharp"]);
+  });
+
+  it("supports an aliased createRequire import", () => {
+    const source = `import { createRequire as makeRequire } from "node:module";
+const mod = makeRequire(import.meta.url)("bcrypt");
+`;
+
+    expect(scanSourceForCreateRequire(source).map((r) => r.specifier)).toEqual(["bcrypt"]);
+  });
+
+  it("supports member access on a module namespace", () => {
+    const source = `import mod from "node:module";
+const req = mod.createRequire(import.meta.url);
+const pg = req("pg");
+`;
+
+    expect(scanSourceForCreateRequire(source).map((r) => r.specifier)).toEqual(["pg"]);
+  });
+
+  it("supports CJS destructuring of createRequire", () => {
+    const source = `const { createRequire } = require("module");
+const req = createRequire(__filename);
+const lib = req("canvas");
+`;
+
+    expect(scanSourceForCreateRequire(source).map((r) => r.specifier)).toEqual(["canvas"]);
+  });
+
+  it("keeps subpath and scoped specifiers intact", () => {
+    const source = `import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+const a = req("mssql/lib/tedious");
+const b = req("@aws-sdk/client-s3");
+`;
+
+    expect(scanSourceForCreateRequire(source).map((r) => r.specifier)).toEqual([
+      "mssql/lib/tedious",
+      "@aws-sdk/client-s3",
+    ]);
+  });
+
+  it("ignores relative, absolute, and internal-import specifiers", () => {
+    const source = `import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+req("./data.json");
+req("../other.js");
+req("/abs/path.js");
+req("#internal/thing");
+`;
+
+    expect(scanSourceForCreateRequire(source)).toEqual([]);
+  });
+
+  it("ignores node builtins with and without the node: prefix", () => {
+    const source = `import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+req("fs");
+req("node:path");
+req("fs/promises");
+`;
+
+    expect(scanSourceForCreateRequire(source)).toEqual([]);
+  });
+
+  it("ignores non-literal specifiers", () => {
+    const source = `import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+const name = "mssql";
+req(name);
+`;
+
+    expect(scanSourceForCreateRequire(source)).toEqual([]);
+  });
+
+  it("ignores a createRequire result that is only assigned, never called", () => {
+    const source = `import { createRequire } from "node:module";
+globalThis.require = createRequire(import.meta.url);
+`;
+
+    expect(scanSourceForCreateRequire(source)).toEqual([]);
+  });
+
+  it("returns nothing when the source doesn't mention createRequire", () => {
+    const source = `import mssql from "mssql";
+export const pool = mssql.connect();
+`;
+
+    expect(scanSourceForCreateRequire(source)).toEqual([]);
+  });
+
+  it("does not treat unrelated variables with similar names as require functions", () => {
+    const source = `import { createRequire } from "node:module";
+const req = createRequire(import.meta.url);
+const reqCount = tally("metrics");
+obj.req("not-a-require");
+`;
+
+    expect(scanSourceForCreateRequire(source)).toEqual([]);
+  });
+});
+
+describe("CreateRequireCollector", () => {
+  it("collects createRequire usages from bundle inputs", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "create-require-collector-"));
+
+    try {
+      const entryPoint = join(dir, "entry.ts");
+      await writeFile(
+        entryPoint,
+        `import { createRequire } from "node:module";
+export const mssql = createRequire(import.meta.url)("mssql");
+`
+      );
+
+      const collector = new CreateRequireCollector(dir);
+
+      await build({
+        entryPoints: [entryPoint],
+        bundle: true,
+        metafile: true,
+        write: false,
+        format: "esm",
+        platform: "node",
+        outdir: dir,
+        absWorkingDir: dir,
+        logLevel: "silent",
+        plugins: [collector.plugin],
+      });
+
+      expect(collector.usages).toHaveLength(1);
+      expect(collector.usages[0]).toMatchObject({
+        specifier: "mssql",
+        packageName: "mssql",
+        file: "entry.ts",
+        line: 2,
+      });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("packageNameForSpecifier", () => {
+  it("extracts the package name from plain, subpath, and scoped specifiers", () => {
+    expect(packageNameForSpecifier("mssql")).toBe("mssql");
+    expect(packageNameForSpecifier("mssql/lib/tedious")).toBe("mssql");
+    expect(packageNameForSpecifier("@aws-sdk/client-s3")).toBe("@aws-sdk/client-s3");
+    expect(packageNameForSpecifier("@aws-sdk/client-s3/dist/index.js")).toBe("@aws-sdk/client-s3");
+  });
+});