feat(esbuild): add DI worker bundling support

Add support for bundling the Live Debugging (LD) / Dynamic
Instrumentation (DI) worker when building applications with esbuild.
This enables LD/DI features to work in bundled applications.

The plugin now:
- Emits a separate worker bundle (dd-trace-debugger-worker.cjs)
  alongside the main application bundle
- Patches the debugger module to reference the emitted worker
- Patches the worker's dd-trace lookup to use global._ddtrace for
  bundler compatibility

Author: watson

integration-tests/esbuild/build-and-test-debugger-worker.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+'use strict'
+
+/* eslint-disable no-console */
+
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const { spawnSync } = require('node:child_process')
+
+const esbuild = require('esbuild')
+const ddPlugin = require('../../esbuild')
+
+const MAIN_SCRIPT = './di-worker-out.js'
+const WORKER_SCRIPT = './dd-trace-debugger-worker.cjs'
+
+// Create a minimal test app that initializes dd-trace with DI enabled
+const testAppCode = `
+'use strict';
+const tracer = require('../../').init();
+
+// Just verify the process can start with DI enabled
+console.log('DI worker test: app started successfully');
+
+// Give it a moment to initialize, then exit cleanly
+setTimeout(() => {
+  process.exit(0);
+}, 100);
+`
+
+// Write the test app to a temp file
+const testAppPath = './di-test-app.js'
+fs.writeFileSync(testAppPath, testAppCode)
+
+esbuild.build({
+  entryPoints: [testAppPath],
+  bundle: true,
+  outfile: MAIN_SCRIPT,
+  plugins: [ddPlugin],
+  platform: 'node',
+  target: ['node18'],
+  external: [
+    // dead code paths introduced by knex if required
+    'pg',
+    'mysql2',
+    'better-sqlite3',
+    'sqlite3',
+    'mysql',
+    'oracledb',
+    'pg-query-stream',
+    'tedious',
+    '@yaacovcr/transform',
+  ],
+}).then(() => {
+  // Verify the worker bundle was emitted
+  assert.ok(
+    fs.existsSync(WORKER_SCRIPT),
+    `Expected DI worker bundle to exist at ${WORKER_SCRIPT}`
+  )
+
+  // Verify the worker file is a valid CJS file with substantial content
+  const workerContent = fs.readFileSync(WORKER_SCRIPT, 'utf8')
+  assert.ok(
+    workerContent.length > 1000,
+    'DI worker bundle should have substantial content'
+  )
+  assert.ok(
+    workerContent.includes('Debugger.paused') || workerContent.includes('debugger'),
+    'DI worker bundle should contain debugger-related code'
+  )
+
+  // Verify the patched dd-trace lookup is present in the worker
+  assert.ok(
+    workerContent.includes('global._ddtrace'),
+    'DI worker bundle should have patched dd-trace lookup using global._ddtrace'
+  )
+
+  // Verify the main bundle references the worker file
+  const mainContent = fs.readFileSync(MAIN_SCRIPT, 'utf8')
+  assert.ok(
+    mainContent.includes('dd-trace-debugger-worker.cjs'),
+    'Main bundle should reference the DI worker bundle'
+  )
+
+  console.log('DI worker bundle emitted correctly')
+
+  // Run the bundled app with DI enabled to verify it starts without crashing
+  // Note: The app will exit quickly since we're just testing startup
+  const { status, stderr } = spawnSync('node', [MAIN_SCRIPT], {
+    env: {
+      ...process.env,
+      DD_TRACE_DEBUG: 'true',
+      DD_DYNAMIC_INSTRUMENTATION_ENABLED: 'true',
+    },
+    encoding: 'utf8',
+    timeout: 10000,
+  })
+
+  // Log stderr for debugging if there's an issue
+  if (stderr.length) {
+    console.error('stderr:', stderr)
+  }
+
+  // The app should exit cleanly (status 0)
+  // Note: DI may not fully initialize in this short-running test, but the process should not crash
+  if (status !== 0) {
+    throw new Error(`Generated script exited with unexpected exit code: ${status}`)
+  }
+
+  console.log('DI worker test: app ran successfully with DI enabled')
+  console.log('ok')
+}).catch((err) => {
+  console.error(err)
+  process.exit(1)
+}).finally(() => {
+  fs.rmSync(testAppPath, { force: true })
+  fs.rmSync(MAIN_SCRIPT, { force: true })
+  fs.rmSync(WORKER_SCRIPT, { force: true })
+})

integration-tests/esbuild/index.spec.js

@@ -61,6 +61,7 @@ esbuildVersions.forEach((version) => {
         process.exit(1)
       } finally {
         rmSync('./out.js', { force: true })
+        rmSync('./dd-trace-debugger-worker.cjs', { force: true })
       }
     })
 
@@ -106,11 +107,18 @@ esbuildVersions.forEach((version) => {
       })
     })
 
+    it('emits debugger worker bundle and allows LD/DI-enabled startup', () => {
+      execSync('node ./build-and-test-debugger-worker.js', {
+        timeout,
+      })
+    })
+
     describe('ESM', () => {
       afterEach(() => {
         rmSync('./out.mjs', { force: true })
         rmSync('./out.js', { force: true })
         rmSync('./basic-test.mjs', { force: true })
+        rmSync('./dd-trace-debugger-worker.cjs', { force: true })
       })
 
       it('works', () => {

packages/datadog-esbuild/index.js

@@ -49,6 +49,11 @@ for (const builtin of RAW_BUILTINS) {
 // eslint-disable-next-line eslint-rules/eslint-process-env
 const DD_IAST_ENABLED = process.env.DD_IAST_ENABLED?.toLowerCase() === 'true' || process.env.DD_IAST_ENABLED === '1'
 
+const DEBUGGER_WORKER_FILENAME = 'dd-trace-debugger-worker.cjs'
+
+// Path pattern to match the debugger index.js inside dd-trace package
+const DEBUGGER_INDEX_PATH = path.join('dd-trace', 'src', 'debugger', 'index.js')
+
 module.exports.name = 'datadog-esbuild'
 
 function isESMBuild (build) {
@@ -372,7 +377,146 @@ register(${JSON.stringify(toRegister)}, _, set, get, ${JSON.stringify(data.raw)}
         resolveDir: path.dirname(args.path),
       }
     }
+
+    // Rewrite the debugger worker path so it points to the emitted worker bundle
+    if (args.path.includes(DEBUGGER_INDEX_PATH)) {
+      log.debug('TRANSFORM DEBUGGER PATH: %s', args.path)
+      let contents = fs.readFileSync(args.path, 'utf8')
+
+      // Replace: join(__dirname, 'devtools_client', 'index.js')
+      // With: join(__dirname, 'dd-trace-debugger-worker.cjs')
+      // The bundled __dirname will point to the output directory where we emit the worker bundle
+      contents = contents.replaceAll(
+        /join\(__dirname,\s*['"]devtools_client['"],\s*['"]index\.js['"]\)/g,
+        `join(__dirname, '${DEBUGGER_WORKER_FILENAME}')`
+      )
+
+      return {
+        contents,
+        loader: 'js',
+        resolveDir: path.dirname(args.path),
+      }
+    }
   })
+
+  // Build the Dynamic Instrumentation worker bundle as a secondary artifact
+  build.onEnd(async (result) => {
+    if (result.errors.length > 0) {
+      log.debug('Skipping DI worker build due to main build errors')
+      return
+    }
+
+    const outputDir = getOutputDirectory(build.initialOptions)
+    if (!outputDir) {
+      log.warn(
+        // eslint-disable-next-line @stylistic/max-len
+        'Cannot emit Live Debugger/Dynamic Instrumentation worker bundle. No outfile or outdir specified. LD/DI will not work in the bundled application.'
+      )
+      return
+    }
+
+    await buildDebuggerWorker(build.initialOptions, outputDir, build.esbuild)
+  })
+}
+
+/**
+ * Determine the output directory from esbuild options
+ *
+ * @param {object} initialOptions - esbuild initial options
+ * @returns {string | null} - Output directory path or null
+ */
+function getOutputDirectory (initialOptions) {
+  if (initialOptions.outdir) {
+    return initialOptions.outdir
+  }
+  if (initialOptions.outfile) {
+    return path.dirname(initialOptions.outfile)
+  }
+  return null
+}
+
+/**
+ * Build the Dynamic Instrumentation worker bundle
+ *
+ * @param {object} parentOptions - Parent build options
+ * @param {string} outputDir - Output directory for the worker bundle
+ * @param {object} esbuild - esbuild module instance from the parent build
+ */
+async function buildDebuggerWorker (parentOptions, outputDir, esbuild) {
+  if (!esbuild) {
+    log.warn('esbuild instance not available. LD/DI worker bundle cannot be built.')
+    return
+  }
+
+  // Resolve the devtools_client entry point from the installed dd-trace package
+  let workerEntryPoint
+  try {
+    // First try to resolve dd-trace to find its installation path
+    // eslint-disable-next-line n/no-missing-require -- dd-trace is a peer dependency
+    const ddTracePath = require.resolve('dd-trace/package.json')
+    workerEntryPoint = path.join(path.dirname(ddTracePath), 'src', 'debugger', 'devtools_client', 'index.js')
+  } catch {
+    // Fallback: resolve relative to this plugin (for development/linked packages)
+    workerEntryPoint = path.join(__dirname, '..', 'dd-trace', 'src', 'debugger', 'devtools_client', 'index.js')
+  }
+
+  if (!fs.existsSync(workerEntryPoint)) {
+    log.warn(
+      'Could not find DI worker entry point at %s. LD/DI will not work in the bundled application.',
+      workerEntryPoint
+    )
+    return
+  }
+
+  const workerOutfile = path.join(outputDir, DEBUGGER_WORKER_FILENAME)
+
+  log.debug('Building DI worker bundle: %s -> %s', workerEntryPoint, workerOutfile)
+
+  // Plugin to patch the trace/span lookup to use global._ddtrace
+  const patchDDTracePlugin = {
+    name: 'patch-ddtrace-lookup',
+    setup (workerBuild) {
+      workerBuild.onLoad({ filter: /devtools_client[/\\]index\.js$/ }, (args) => {
+        let contents = fs.readFileSync(args.path, 'utf8')
+
+        // Replace the dd-trace require expression with a bundler-safe version
+        // Original: global.require('dd-trace').scope().active()?.context()
+        // New: (global._ddtrace ?? global.require?.('dd-trace'))?.scope?.()?.active?.()?.context?.()
+        contents = contents.replaceAll(
+          /global\.require\(['"]dd-trace['"]\)\.scope\(\)\.active\(\)\?\.context\(\)/g,
+          "(global._ddtrace ?? global.require?.('dd-trace'))?.scope?.()?.active?.()?.context?.()"
+        )
+
+        return {
+          contents,
+          loader: 'js',
+        }
+      })
+    },
+  }
+
+  try {
+    await esbuild.build({
+      entryPoints: [workerEntryPoint],
+      bundle: true,
+      platform: 'node',
+      format: 'cjs',
+      outfile: workerOutfile,
+      target: parentOptions.target || ['node18'],
+      // Keep Node.js builtins external
+      external: [...RAW_BUILTINS, ...RAW_BUILTINS.map(m => `node:${m}`)],
+      // Ensure function/class names are preserved for debugging
+      keepNames: true,
+      plugins: [patchDDTracePlugin],
+      // Don't minify the worker - keep it debuggable
+      minify: false,
+      logLevel: 'warning',
+    })
+
+    log.debug('DI worker bundle emitted: %s', workerOutfile)
+  } catch (err) {
+    log.warn('Failed to build DI worker bundle: %s', err.message)
+  }
 }
 
 // @see https://github.com/nodejs/node/issues/47000