diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx new file mode 100644 index 0000000000000..5c5739455a805 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -0,0 +1,80 @@ +--- +title: --import CLI flag +sidebar_order: 2 +description: "Learn about using the node `--import` CLI flag." +--- + +## Understanding the `--import` CLI Flag + +The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node allows you to preload modules before the application starts. +If you cannot use the SDK's default dynamic import behaviour, setting +this flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the rest of the application runs. + +## Scenarios where `--import` does not work + +- You're not able to add Node CLI flags or environment variables that are scoped to the function runtime +- As of now, Netlify only supports adding scoped environment variables in the paid plan +- As of now, Vercel does not provide an option for scoping environment variables + +If any of those points apply to you, you cannot use the `--import` flag to initialize Sentry on the server-side. +Check out the guide for using dynamic import instead. + +## Initializing Sentry with `--import` + +To successfully use the `--import` flag, follow these steps: + +### 1. Disable Dynamic Import + +First, disable the dynamic import by setting `dynamicImportForServerEntry` to `false`: + +```javascript {filename: nuxt.config.ts} {5} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + + sentry: { + dynamicImportForServerEntry: false, + }, +}); +``` + +By disabling the dynamic import, the SDK will add the Sentry server config to the build output (typically `.output/server/sentry.server.config.mjs`). + +### 2. Adding `--import` to `node` command + +After building your Nuxt app with `nuxi build`, add the `--import` flag followed by the Sentry server config path to the `node` command. +With the default Nitro Node preset, this typically looks like this: + +```bash +node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs +``` + +Check the log at the very end of the console output after building the application. +This will print the node command with the server entry path for your application (`node .output/server/index.mjs` with the Node preset). +Make sure to update the paths accordingly, especially when using a different Nitro preset. + +To make things easier, add a script in the `package.json`: + +```json {filename:package.json} +{ + "scripts": { + "preview": "NODE_OPTIONS='--import .//server/sentry.server.config.mjs' nuxt preview", + "start": "node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs" + } +} +``` + +### 3. Adding `--import` flag in production + +To be able to set up Sentry in production, the `--import` flag needs to be added wherever you run your application's production build output. +Consult your hosting provider's documentation for specific implementation details. +Most deployment platforms support this through two primary methods: + +#### Option 1: Direct CLI Flag +```bash +node --import .output/server/sentry.server.config.mjs your-server-entry.mjs +``` + +#### Option 2: Environment Variable +```bash +NODE_OPTIONS='--import .output/server/sentry.server.config.mjs' +``` diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx new file mode 100644 index 0000000000000..9bc5e4c7a6735 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -0,0 +1,76 @@ +--- +title: Dynamic Import (default) +sidebar_order: 1 +description: "Learn about how the Nuxt SDK leverages dynamic input() in the build output." +--- + +## 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. +This early initialization is required to set up the SDK's instrumentation of various libraries correctly. + +## Initializing Sentry with Dynamic `import()` + +By default, the Sentry Nuxt SDK includes a Rollup plugin which wraps the server entry file with a dynamic `import()`. +With this, Sentry can be initialized before all other modules of the application. + +The server entry file will look something like this: + +```javascript {filename:.output/server/index.mjs} +// Note: 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 + +We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt). +We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). As a temporary workaround, you can add the following overrides to your application: + +```json {tabTitle:npm} {filename:package.json} +"overrides": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" +} +``` +```json {tabTitle:yarn} {filename:package.json} +"resolutions": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" +} +``` +```json {tabTitle:pnpm} {filename:package.json} +"pnpm": { + "overrides": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" + } +} +``` + +You can also check out the guide for using the CLI flag `--import` as this might be a better choice for you. + + +## 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. +In case your serverless function has another, custom name you can override this with `entrypointWrappedFunctions`: + + +```javascript {filename: nuxt.config.ts} {7} +export default defineNuxtConfig({ + modules: ["@sentry/nuxt/module"], + + sentry: { + // Customize detected function names + // Default value: ['default', 'handler', 'server'] + entrypointWrappedFunctions: ['customFunctionName'] + }, +}); +``` diff --git a/docs/platforms/javascript/guides/nuxt/install/index.mdx b/docs/platforms/javascript/guides/nuxt/install/index.mdx new file mode 100644 index 0000000000000..547a8bda34c89 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/index.mdx @@ -0,0 +1,14 @@ +--- +title: Installation Methods +sidebar_order: 1.5 +description: "Review our alternate installation methods." +--- + + + +Nuxt uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). +Those customization hooks need to be registered before the rest of the application. + +To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: + + diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx index 22dcf2dc7095a..edad433089fa8 100644 --- a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx @@ -105,7 +105,8 @@ dotenv.config(); #### Troubleshoot Errors during Server Startup -In case you are experiencing problems after adding `sentry.server.config.ts` and building the project, you can check out Troubleshooting. +In case you are experiencing problems after adding `sentry.server.config.ts` and building the project, you can check out Troubleshooting +or read through the different installation methods. ## Source Maps Upload