Dynamic Import (experimental)

Understanding the import() expression

The import() expression, or dynamic import, enables flexible, conditional module loading in ESM. Node.js will generate a separate module graph for any code wrapped in a dynamic import(). This separate graph is evaluated after all modules, which are statically imported.

By using the Sentry Nuxt SDK, the server-side application will be wrapped in a dynamic import(), while the Sentry configuration will be imported with a static import. This makes it possible to initialize the Sentry Nuxt SDK at startup, while the Nitro server runtime loads later because it is import()ed. This early initialization of Sentry is required to correctly set up the SDK's instrumentation of various libraries.

Scenarios where import() doesn't work

Depending on your setup and which version of Nitro is used, the server-side is sometimes not correctly initialized. The build output must not include a regular import of the Nitro runtime (e.g. import './chunks/nitro/nitro.mjs'). See the (GitHub issue here) for more information.

As a temporary workaround, you can add the following overrides in your application:

"overrides": {
  "nitropack": "~2.9.7",
  "@vercel/nft": "^0.27.4"
}

You can also check out the guide for installing the SDK with the CLI flag --import or limited-server-tracing.

Initializing Sentry with Dynamic import()

Enable the dynamic import() by setting autoInjectServerSentry:

export default defineNuxtConfig({
  sentry: {
    autoInjectServerSentry: "experimental_dynamic-import",
  },
});

After setting this, the Sentry Nuxt SDK will add build-time configuration so that your app will be wrapped with import(), ensuring that Sentry can be initialized before any other modules.

The Nuxt server entry file will look something like this:

// Note: The file may have some imports and code, related to debug IDs
Sentry.init({
  dsn: "...",
});

import("./chunks/nitro/nitro.mjs").then(function (n) {
  return n.r;
});

Re-exporting serverless handler functions

Sentry automatically detects serverless handler functions in the build output and re-exports them from the server entry file.

By default, Sentry re-exports functions named handler, server, and default exports. This will work in most cases and no other action is required. If your serverless function has a custom name, you can override it with experimental_entrypointWrappedFunctions:

export default defineNuxtConfig({
  modules: ["@sentry/nuxt/module"],

  sentry: {
    // Customize detected function names
    // Default value: ['default', 'handler', 'server']
    experimental_entrypointWrappedFunctions: ["customFunctionName"],
  },
});