From f2fab2f725ec25c05f63faa5ffd297676948a4e8 Mon Sep 17 00:00:00 2001 From: Attila Szegedi Date: Tue, 4 Feb 2025 16:59:17 +0100 Subject: [PATCH 1/2] Add Next.js-specific bundling information --- .../dd_libraries/nodejs.md | 48 ++++++++++++++++++- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md index b0f25ab15c795..0dbb8d7fd7b11 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md @@ -130,7 +130,7 @@ Datadog recommends you have custom-built bundler plugins. These plugins are able **Note**: Some applications can have 100% of modules bundled, however native modules still need to remain external to the bundle. -#### Esbuild support +#### Bundling with Esbuild This library provides experimental esbuild support in the form of an esbuild plugin, and requires at least Node.js v16.17 or v18.7. To use the plugin, make sure you have `dd-trace@3+` installed, and then require the `dd-trace/esbuild` module when building your bundle. @@ -148,7 +148,7 @@ esbuild.build({ platform: 'node', // allows built-in modules to be required target: ['node16'], external: [ - // esbuild cannot bundle native modules + // required if you use native metrics '@datadog/native-metrics', // required if you use profiling @@ -170,6 +170,48 @@ esbuild.build({ }) ``` +#### Bundling with Next.js + +If you are using Next.js or another framework relying on webpack to bundle your application, add a declaration +similar to the one for webpack inside your `next.config.js` configuration file: + +```javascript +/** @type {import('next').NextConfig} */ +const nextConfig = { + // ... non-relevant parts omitted, substitute your own config ... + + // this custom webpack config is required for Datadog tracing to work + webpack: ( + config, + { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack } + ) => { + const externals = [ + // required if you use native metrics + '@datadog/native-metrics', + + // required if you use profiling + '@datadog/pprof', + + // required if you use Datadog security features + '@datadog/native-appsec', + '@datadog/native-iast-taint-tracking', + '@datadog/native-iast-rewriter', + + // required if you encounter graphql errors during the build step + 'graphql/language/visitor', + 'graphql/language/printer', + 'graphql/utilities' + ]; + config.externals.push(...externals); + return config; + }, +}; + +export default nextConfig; +``` + +#### General bundling remarks + **Note**: Due to the usage of native modules in the tracer, which are compiled C++ code, (usually ending with a `.node` file extension), you need to add entries to your `external` list. Currently native modules used in the Node.js tracer live inside of `@datadog` prefixed packages. This will also require that you ship a `node_modules/` directory alongside your bundled application. You don't need to ship your entire `node_modules/` directory as it would contain many superfluous packages that should be contained in your bundle. To generate a smaller `node_modules/` directory with only the required native modules, (and their dependencies) you can first determine the versions of packages that you need, then create a temporary directory to install them into, and copy the resulting `node_modules/` directory from it. For example: @@ -188,6 +230,8 @@ npm install @datadog/native-metrics@2.0.0 @datadog/pprof@5.0.0 cp -R ./node_modules path/to/bundle ``` +(In case of Next.js the `path/to/bundle` is usually the `.next/standalone` directory of your app.) + At this stage you should be able to deploy your bundle, (which is your application code and most of your dependencies), with the `node_modules/` directory, which contains the native modules and their dependencies. ## Configuration From dc822edf1396d154a2f02760efe7c28b992aafbb Mon Sep 17 00:00:00 2001 From: Attila Szegedi Date: Thu, 6 Feb 2025 12:07:50 +0100 Subject: [PATCH 2/2] Change parenthetical to note as per suggestion Co-authored-by: Thomas Hunter II --- .../automatic_instrumentation/dd_libraries/nodejs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md index 0dbb8d7fd7b11..dd3bdd4edf8c8 100644 --- a/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md +++ b/content/en/tracing/trace_collection/automatic_instrumentation/dd_libraries/nodejs.md @@ -230,7 +230,7 @@ npm install @datadog/native-metrics@2.0.0 @datadog/pprof@5.0.0 cp -R ./node_modules path/to/bundle ``` -(In case of Next.js the `path/to/bundle` is usually the `.next/standalone` directory of your app.) +**Note**: In case of Next.js the `path/to/bundle` is usually the `.next/standalone` directory of your app. At this stage you should be able to deploy your bundle, (which is your application code and most of your dependencies), with the `node_modules/` directory, which contains the native modules and their dependencies.