Skip to content

Commit

Permalink
update installation pages
Browse files Browse the repository at this point in the history
  • Loading branch information
s1gr1d committed Nov 28, 2024
1 parent 433600d commit caa2c80
Show file tree
Hide file tree
Showing 4 changed files with 88 additions and 5 deletions.
9 changes: 7 additions & 2 deletions docs/platforms/javascript/guides/nuxt/install/cli-import.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,17 @@ 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.js allows you to preload modules before your application starts.
The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node allows you to preload modules before the application starts.
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 are 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 <PlatformLink to="/install/dynamic-import/">dynamic import</PlatformLink> as this might be a better choice for you.

## Initializing Sentry with `--import`

Expand Down Expand Up @@ -58,7 +63,7 @@ To make things easier, add a script in the `package.json`:
}
```

### 3. Adding the CLI flag in production
### 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.
Expand Down
74 changes: 73 additions & 1 deletion docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,76 @@ sidebar_order: 1
description: "Learn about how the Nuxt SDK leverages dynamic input() in the build output."
---

TODO
## 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.

## Scenarios where `import()` does not 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 <PlatformLink to="/install/cli-import//">CLI flag `--import`</PlatformLink> as this might be a better choice for you.


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

## 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} {6}
export default defineNuxtConfig({
modules: ["@sentry/nuxt/module"],

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




7 changes: 6 additions & 1 deletion docs/platforms/javascript/guides/nuxt/install/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,5 +6,10 @@ description: "Review our alternate installation methods."

<PageGrid />

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.

TODO: Nuxt is using ES Modules on the server-side so...
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:

- Dynamically import server code after initializing Sentry (default)
- Preload Sentry configuration with the Node `--import` CLI flag
3 changes: 2 additions & 1 deletion docs/platforms/javascript/guides/nuxt/manual-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>.
In case you are experiencing problems after adding `sentry.server.config.ts` and building the project, you can check out <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
or read through the different <PlatformLink to="/install">installation methods</PlatformLink>.

## Source Maps Upload

Expand Down

0 comments on commit caa2c80

Please sign in to comment.