Dynamic Import (experimental)

Understanding the import() expression

The import() expression (also called "dynamic import") allows conditional and flexible module loading in ESM. For the Sentry Nuxt SDK, it provides an approach to initialize server-side configuration before application startup.

The Sentry Nuxt SDK will be initialized before any other code runs and the Nitro server runtime code will be loaded later because of import()ing it. This early initialization is required to set up the SDK's instrumentation of various libraries correctly.

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 adds some build-time configuration to ensure your app is wrapped with import(). With this, Sentry can be initialized before all other modules of the application.

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;
});

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 a CLI flag --import or a top-level import.

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"],
  },
});