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

## Summary

A package loaded with `createRequire(import.meta.url)("pkg")` is
invisible to esbuild: the call is never resolved, so the package is
neither bundled nor collected as an external to install in the deployed
image. The deploy succeeds with zero diagnostics and the task fails at
runtime with a module-not-found error, which can surface as something
far more confusing when a library maps errors coarsely (a database
driver loaded this way can look exactly like a connection failure). It
also works fine in `trigger dev` because the local `node_modules`
exists, making the production-only failure extra misleading.

Both `deploy` and `dev` builds now warn about this, pointing at the
exact file and line, with a note showing the exact config that fixes it:

```
▲ [WARNING] "mssql" is loaded with createRequire() but won't be available in the deployed image, so loading it will fail at runtime. The bundler can't follow createRequire() calls, so "mssql" is neither bundled into your code nor installed in the image. [plugin create-require-collector]

    src/db.ts:12:14:
      12 │ const mssql = createRequire(import.meta.url)("mssql");
         ╵               ^

  To fix this, install "mssql" into the image by adding the additionalPackages build extension to your trigger.config.ts:

    import { additionalPackages } from "@trigger.dev/build/extensions/core";

    export default defineConfig({
      // ...
      build: {
        extensions: [additionalPackages({ packages: ["mssql"] })],
      },
    });

  Alternatively, replace the createRequire() call with a static import so the package is bundled. Docs: https://trigger.dev/docs/config/extensions/additionalPackages
```

In `dev` the message instead explains that the code works locally but
deploys of it will fail, so the problem is caught while the code is
being written rather than after a deploy.

## How it works

An esbuild plugin scans the bundle's input files outside `node_modules`
for string-literal specifiers passed to `createRequire`-created require
functions: `createRequire(...)("pkg")`, `const req = createRequire(...);
req("pkg")`, `req.resolve("pkg")`, aliased imports, namespace access,
CJS destructuring, and dynamic `import("node:module")` bindings. Sources
are parsed with `@babel/parser` (already in the dependency tree), so
comments, strings, templates, regex literals and JSX can't confuse the
scan; a file that fails to parse is skipped. Relative paths and node
builtins never warn.

A usage only warns when the package will actually be missing from the
image. On deploys the resolved manifest externals are the source of
truth (extension-installed layers are already merged in when the warning
runs); `build.external` alone deliberately does not suppress, because
marking a package external installs nothing when nothing statically
imports it. In dev, which predicts a future deploy, suppression
additionally trusts what extensions declare they install, and stays
silent entirely when that can't be determined (an extension hook throws,
or an older `@trigger.dev/build`'s additionalPackages predates the
declaration hook), so dev never makes a false "deploys will fail" claim.
`additionalPackages` declares its packages via a new diagnostics-only
`BuildExtension` field, `installedPackagesForTarget`, which the bundler
ignores: bundling output is unchanged for existing projects.

Detection is name-based, module-level, and deliberately per-file:
computed specifiers, shadowed names, and require helpers imported from
other files are not followed (those degrade to today's behavior, an
unwarned runtime failure), and scanning is scoped to user code because
bundled libraries legitimately use optional-require patterns that would
drown real findings in noise. Packages named in build-layer install
commands (`RUN npm install ...`) are suppressed individually.

Deploys also now surface esbuild's own bundle warnings for user files
(for example `require()` with a non-literal argument), which were
previously discarded on the deploy path; `trigger dev` already showed
them.

Author: matt-aitken

.changeset/warn-createrequire-deploy.md

@@ -0,0 +1,7 @@
+---
+"trigger.dev": patch
+"@trigger.dev/build": patch
+"@trigger.dev/core": patch
+---
+
+The `trigger.dev deploy` and `trigger.dev dev` commands now warn (with the suggested fix) when your code loads a package through `createRequire()` that won't be available in the deployed image. Previously it would fail at runtime in production to load the package. Deploys also now show bundler warnings for your code instead of discarding them.

docs/config/extensions/custom.mdx

@@ -80,7 +80,7 @@ export default defineConfig({
     extensions: [
       {
         name: "my-extension",
-        externalsForTarget: async (target) => {
+        externalsForTarget: (target) => {
           return ["my-dependency"];
         },
       },
@@ -89,6 +89,19 @@ export default defineConfig({
 });
 ```
 
+### installedPackagesForTarget
+
+This tells build diagnostics which packages your extension installs into the deployed image for a given target, so warnings (like the one for packages loaded via `createRequire()`) don't fire for packages that will actually be available at runtime. The bundler ignores this hook, so declaring it never changes the build output. Only implement it if your extension installs packages; extensions without it are assumed to install none.
+
+```ts
+{
+  name: "my-extension",
+  installedPackagesForTarget: (target) => {
+    return target === "deploy" ? ["my-dependency"] : [];
+  },
+}
+```
+
 ### onBuildStart
 
 This hook runs before the build starts. It receives the `BuildContext` object as an argument.

packages/build/src/extensions/core/additionalPackages.ts

@@ -19,6 +19,23 @@ export type AdditionalPackagesOptions = {
 export function additionalPackages(options: AdditionalPackagesOptions): BuildExtension {
   return {
     name: "additionalPackages",
+    installedPackagesForTarget(target) {
+      if (target !== "deploy") {
+        return [];
+      }
+
+      const names: string[] = [];
+
+      for (const pkg of options.packages) {
+        try {
+          names.push(parsePackageName(pkg).name);
+        } catch {
+          continue;
+        }
+      }
+
+      return names;
+    },
     async onBuildStart(context) {
       if (context.target !== "deploy") {
         return;

packages/build/src/extensions/prisma.ts

@@ -815,6 +815,14 @@ export class PrismaEngineOnlyModeExtension implements BuildExtension {
     this._binaryTarget = options.binaryTarget ?? "debian-openssl-3.0.x";
   }
 
+  installedPackagesForTarget(target: BuildTarget) {
+    if (target !== "deploy") {
+      return [];
+    }
+
+    return ["@prisma/engines"];
+  }
+
   async onBuildComplete(context: BuildContext, manifest: BuildManifest) {
     if (context.target === "dev") {
       return;

packages/cli-v3/package.json

@@ -107,6 +107,7 @@
     "ini": "^5.0.0",
     "json-stable-stringify": "^1.3.0",
     "jsonc-parser": "3.2.1",
+    "@babel/parser": "^7.29.7",
     "magicast": "^0.3.4",
     "minimatch": "^10.0.1",
     "mlly": "^1.7.1",

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

@@ -1,6 +1,17 @@
 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 {
+  BundleResult,
+  bundleWorker,
+  createBuildManifestFromBundle,
+  logBuildWarnings,
+} from "./bundle.js";
+import {
+  collectCreateRequireWarningMessages,
+  CreateRequireCollector,
+  extensionInstalledPackageMatchers,
+  NODE_MODULES_SEGMENT_REGEX,
+} from "./createRequireWarnings.js";
 import { bundleSkills } from "./bundleSkills.js";
 import {
   createBuildContext,
@@ -47,6 +58,8 @@ export async function buildWorker(options: BuildWorkerOptions) {
 
   const resolvedConfig = options.resolvedConfig;
 
+  const extensionPackages = extensionInstalledPackageMatchers(resolvedConfig);
+
   const externalsExtension = createExternalsBuildExtension(
     options.target,
     resolvedConfig,
@@ -72,6 +85,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 +95,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 +145,23 @@ export async function buildWorker(options: BuildWorkerOptions) {
   buildManifest = await notifyExtensionOnBuildComplete(buildContext, buildManifest);
 
   if (options.target !== "dev") {
+    const buildWarnings = [
+      ...bundleResult.warnings.filter(
+        (warning) =>
+          !warning.location?.file || !NODE_MODULES_SEGMENT_REGEX.test(warning.location.file)
+      ),
+      ...collectCreateRequireWarningMessages({
+        usages: createRequireCollector.usages,
+        buildManifest,
+        extensionPackages,
+        target: options.target,
+      }),
+    ];
+
+    if (buildWarnings.length > 0) {
+      logBuildWarnings(buildWarnings, { color: !options.plain });
+    }
+
     buildManifest = options.rewritePaths
       ? rewriteBuildManifestPaths(buildManifest, options.destination)
       : 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,8 +342,14 @@ function dirToEntryPointGlob(dir: string): string[] {
   ];
 }
 
-export function logBuildWarnings(warnings: esbuild.Message[]) {
-  const logs = esbuild.formatMessagesSync(warnings, { kind: "warning", color: true });
+export function logBuildWarnings(
+  warnings: esbuild.PartialMessage[],
+  options: { color?: boolean } = {}
+) {
+  const logs = esbuild.formatMessagesSync(warnings, {
+    kind: "warning",
+    color: options.color ?? true,
+  });
   for (const log of logs) {
     console.warn(log);
   }