Skip to content

Commit caa2c80

Browse files
committed
update installation pages
1 parent 433600d commit caa2c80

File tree

4 files changed

+88
-5
lines changed

4 files changed

+88
-5
lines changed

docs/platforms/javascript/guides/nuxt/install/cli-import.mdx

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,17 @@ description: "Learn about using the node `--import` CLI flag."
66

77
## Understanding the `--import` CLI Flag
88

9-
The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node.js allows you to preload modules before your application starts.
9+
The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node allows you to preload modules before the application starts.
1010
This flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the rest of the application runs.
1111

1212
## Scenarios where `--import` does not work
1313

14+
- You are not able to add Node CLI flags or environment variables that are scoped to the function runtime
15+
- As of now, Netlify only supports adding scoped environment variables in the paid plan
16+
- As of now, Vercel does not provide an option for scoping environment variables
1417

18+
If any of those points apply to you, you cannot use the `--import` flag to initialize Sentry on the server-side.
19+
Check out the guide for using <PlatformLink to="/install/dynamic-import/">dynamic import</PlatformLink> as this might be a better choice for you.
1520

1621
## Initializing Sentry with `--import`
1722

@@ -58,7 +63,7 @@ To make things easier, add a script in the `package.json`:
5863
}
5964
```
6065

61-
### 3. Adding the CLI flag in production
66+
### 3. Adding `--import` flag in production
6267

6368
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.
6469
Consult your hosting provider's documentation for specific implementation details.

docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,76 @@ sidebar_order: 1
44
description: "Learn about how the Nuxt SDK leverages dynamic input() in the build output."
55
---
66

7-
TODO
7+
## Understanding the `import()` expression
8+
9+
The `import()` expression (also called "dynamic import") allows conditional and flexible module loading in ESM.
10+
For the Sentry Nuxt SDK, it provides an approach to initialize server-side configuration before application startup.
11+
12+
## Scenarios where `import()` does not work
13+
14+
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).
15+
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:
16+
17+
```json {tabTitle:npm} {filename:package.json}
18+
"overrides": {
19+
"nitropack": "2.9.7"
20+
"@vercel/nft": "^0.27.4"
21+
}
22+
```
23+
```json {tabTitle:yarn} {filename:package.json}
24+
"resolutions": {
25+
"nitropack": "2.9.7"
26+
"@vercel/nft": "^0.27.4"
27+
}
28+
```
29+
```json {tabTitle:pnpm} {filename:package.json}
30+
"pnpm": {
31+
"overrides": {
32+
"nitropack": "2.9.7"
33+
"@vercel/nft": "^0.27.4"
34+
}
35+
}
36+
```
37+
38+
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.
39+
40+
41+
## Initializing Sentry with Dynamic `import()`
42+
43+
By default, the Sentry Nuxt SDK includes a Rollup plugin which wraps the server entry file with a dynamic `import()`.
44+
With this, Sentry can be initialized before all other modules of the application.
45+
46+
The server entry file will look something like this:
47+
48+
```javascript {filename:.output/server/index.mjs}
49+
// Note: file may have some imports and code related to debug IDs
50+
Sentry.init({
51+
dsn: "..."
52+
});
53+
54+
import('./chunks/nitro/nitro.mjs').then(function (n) { return n.r; });
55+
```
56+
57+
## Re-exporting serverless handler functions
58+
59+
Sentry automatically detects serverless handler functions in the build output and re-exports them from the server entry file.
60+
61+
By default, Sentry re-exports functions named `handler`, `server`, and `default` exports. This will work in most cases and no other action is required.
62+
In case your serverless function has another, custom name you can override this with `entrypointWrappedFunctions`:
63+
64+
65+
```javascript {filename: nuxt.config.ts} {6}
66+
export default defineNuxtConfig({
67+
modules: ["@sentry/nuxt/module"],
68+
69+
sentry: {
70+
// Customize detected function names
71+
// Default value: ['default', 'handler', 'server']
72+
entrypointWrappedFunctions: ['customFunctionName']
73+
},
74+
});
75+
```
76+
77+
78+
79+

docs/platforms/javascript/guides/nuxt/install/index.mdx

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,10 @@ description: "Review our alternate installation methods."
66

77
<PageGrid />
88

9+
Nuxt uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks).
10+
Those customization hooks need to be registered before the rest of the application.
911

10-
TODO: Nuxt is using ES Modules on the server-side so...
12+
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:
13+
14+
- Dynamically import server code after initializing Sentry (default)
15+
- Preload Sentry configuration with the Node `--import` CLI flag

docs/platforms/javascript/guides/nuxt/manual-setup.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,8 @@ dotenv.config();
105105

106106
#### Troubleshoot Errors during Server Startup
107107

108-
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>.
108+
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>
109+
or read through the different <PlatformLink to="/install">installation methods</PlatformLink>.
109110

110111
## Source Maps Upload
111112

0 commit comments

Comments
 (0)