diff --git a/docs/platforms/javascript/common/install/loader.mdx b/docs/platforms/javascript/common/install/loader.mdx index 185d5e156bb01..612f4c6d41a16 100644 --- a/docs/platforms/javascript/common/install/loader.mdx +++ b/docs/platforms/javascript/common/install/loader.mdx @@ -19,6 +19,7 @@ notSupported: - javascript.wasm - javascript.remix - javascript.react-router + - javascript.solidstart - javascript.svelte - javascript.sveltekit - javascript.node diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx index 2f6b1a623e5d5..b5992a562823d 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -55,7 +55,7 @@ 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 +node --import ./.output/server/sentry.server.config.mjs your-server-entry.mjs ``` #### Option 2: Environment Variable diff --git a/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx new file mode 100644 index 0000000000000..ea23fddb76902 --- /dev/null +++ b/docs/platforms/javascript/guides/solidstart/install/cli-import.mdx @@ -0,0 +1,64 @@ +--- +title: --import CLI flag (default) +sidebar_order: 1 +description: "Learn how to use the node --import CLI flag." +--- + +## Understanding the `--import` CLI Flag + +The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node is the default way in ESM to preload a specified module at startup. +Setting this CLI flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the application runs. +This will register Sentry's [loader hook](https://nodejs.org/api/module.html#customization-hooks) and therefore enable proper instrumentation of ESM modules. + +## Scenarios where `--import` does not work + +- You're unable to add Node CLI flags or environment variables scoped to the function runtime, meaning these variables aren't applied in other scopes, such as build time. +- You don't know the path to the SolidStart server folder in the build output +- At this time, it isn't possible to properly configure `--import` in **Netlify**. +- At this time, it isn't possible to properly configure `--import` in **Vercel**. + +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 limited server tracing instead. + +## Initializing Sentry with `--import` + +By default, the SDK will add the Sentry server instrumentation file to the build output (typically, `.output/server/instrument.server.mjs`). + +### 1. Adding `--import` to `node` command + +After building your SolidStart app with `vinxi build`, add the `--import` flag followed by the Sentry server instrumentation file path to the `node` command. +With the default Vinxi Node preset, this typically looks like this: + +```bash +node --import ./.output/server/instrument.server.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 Vinxi preset. + +To make things easier, add a script in the `package.json`: + +```json {filename:package.json} +{ + "scripts": { + "start": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs" + } +} +``` + +### 2. 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/instrument.server.mjs your-server-entry.mjs +``` + +#### Option 2: Environment Variable +```bash +NODE_OPTIONS='--import ./.output/server/instrument.server.mjs' +``` diff --git a/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx new file mode 100644 index 0000000000000..a4bd655734da4 --- /dev/null +++ b/docs/platforms/javascript/guides/solidstart/install/dynamic-import.mdx @@ -0,0 +1,80 @@ +--- +title: Dynamic Import (experimental) +sidebar_order: 3 +description: "Learn about how the SolidStart SDK leverages dynamic input() in the build output." +--- + +## Understanding the `import()` expression + + + This setting is experimental as it is not guaranteed to work with every setup and the underlying functionality could change. + + We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing + + +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 `import`ed. + +By using the Sentry SolidStart SDK, the server-side application will be wrapped in a dynamic `import()`, while the Sentry instrumentation file will be imported with a static `import`. +This makes it possible to initialize the Sentry SolidStart 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 Vinxi is used (and respectively Nitro, as this runs under the hood), 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'`). + +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`: + +```typescript {filename:app.config.ts} {8} +import { defineConfig } from '@solidjs/start/config'; +import { withSentry } from '@sentry/solidstart'; + +export default defineConfig(withSentry( + {}, + { + autoInjectServerSentry: 'experimental_dynamic-import' + }) + ); +``` + +After setting this, the Sentry SolidStart 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 SolidStart server entry file will look something like this: + +```javascript {filename:.output/server/index.mjs} +// 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`: + +```javascript {filename: app.config.ts} {11} + +import { defineConfig } from '@solidjs/start/config'; +import { withSentry } from '@sentry/solidstart'; + +export default defineConfig(withSentry( + {}, + { + autoInjectServerSentry: 'experimental_dynamic-import', + // Customize detected function names + // Default value: ['default', 'handler', 'server'] + experimental_entrypointWrappedFunctions: ['customFunctionName'] + }) + ); +``` diff --git a/docs/platforms/javascript/guides/solidstart/install/index.mdx b/docs/platforms/javascript/guides/solidstart/install/index.mdx new file mode 100644 index 0000000000000..6e7e2b9d20386 --- /dev/null +++ b/docs/platforms/javascript/guides/solidstart/install/index.mdx @@ -0,0 +1,12 @@ +--- +title: Installation Methods +sidebar_order: 1.5 +description: "Review our alternate installation methods." +--- + +SolidStart 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/solidstart/install/limited-server-tracing.mdx b/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx new file mode 100644 index 0000000000000..556aa88f68c27 --- /dev/null +++ b/docs/platforms/javascript/guides/solidstart/install/limited-server-tracing.mdx @@ -0,0 +1,41 @@ +--- +title: Limited Server Tracing +sidebar_order: 2 +description: "Learn how to set up the SolidStart SDK with limited server tracing by adding a top-level import to the build output." +--- + +## Understanding Limited Server Tracing + +Sentry needs to be initialized before the rest of the application runs. +If the default way of adding an `--import` CLI flag doesn't work for you, +enable the SDK to add a top-level `import`. + +The automatically added top-level `import` will then import the Sentry server-side config at the top of the SolidStart server entry file. +In this case, Sentry isn’t initialized before the app starts, but is set up as early as possible. + + + This installation method has fundamental restrictions: + - Only basic `http` and `fetch` instrumentation will work. + - No DB or framework-specific instrumentation will be available. + + We recommend using this only if the `--import` flag is not an option for you. + + +## Initializing Sentry With a Top-level `import` + +Enable the top-level `import` by setting `autoInjectServerSentry`: + +```typescript {filename:app.config.ts} {8} +import { defineConfig } from '@solidjs/start/config'; +import { withSentry } from '@sentry/solidstart'; + +export default defineConfig(withSentry( + {}, + { + autoInjectServerSentry: 'top-level-import' + }) + ); +``` + +By default, the SDK will add the Sentry server instrumentation file to the build output (typically, `.output/server/instrument.server.mjs`). +The SDK will then automatically import this file at the top of the SolidStart server entry file in the build output. diff --git a/platform-includes/getting-started-config/javascript.solidstart.mdx b/platform-includes/getting-started-config/javascript.solidstart.mdx index 97bf45757f447..80be61eb951ec 100644 --- a/platform-includes/getting-started-config/javascript.solidstart.mdx +++ b/platform-includes/getting-started-config/javascript.solidstart.mdx @@ -26,18 +26,9 @@ mount(() => , document.getElementById('app')); ### Server-side Setup -Create an instrument file `instrument.server.mjs`, initialize the Sentry SDK and deploy it alongside your application. -For example by placing it in the `public` folder. +Create an instrument file `instrument.server.ts` in your `src` folder. In this file, initialize the Sentry SDK for your server. - - - Placing `instrument.server.mjs` inside the `public` folder makes it accessible to the outside world. - Consider blocking requests to this file or finding a more appropriate location which your backend can access. - - - - -```javascript {filename:public/instrument.server.mjs} +```javascript {filename:src/instrument.server.ts} import * as Sentry from '@sentry/solidstart'; Sentry.init({ @@ -46,13 +37,31 @@ Sentry.init({ }); ``` +Wrap your SolidStart config with `withSentry`, so this file gets added to your build output. With the default server preset, you can find the file here: `.output/server/instrument.server.mjs`. + +```javascript {filename:app.config.ts} {5-12} +import { withSentry } from '@sentry/solidstart'; +import { defineConfig } from '@solidjs/start/config'; + +export default defineConfig( + withSentry( + { + /* Your SolidStart config */ + }, + { + /* Your Sentry build-time config (such as source map upload options) */ + } + ), +); +``` + ### Instrumentation The Sentry SDK provides [middleware lifecycle](https://docs.solidjs.com/solid-start/advanced/middleware) handlers to enhance data collected by Sentry on the server side by enabling distributed tracing between the client and server. Complete the setup by adding `sentryBeforeResponseMiddleware` to your `src/middleware.ts` file. If you don't have a `src/middleware.ts` file yet, create one: -```typescript {filename:src/middleware.ts} +```typescript {filename:src/middleware.ts} {6} import { sentryBeforeResponseMiddleware } from '@sentry/solidstart'; import { createMiddleware } from '@solidjs/start/middleware'; @@ -66,19 +75,22 @@ export default createMiddleware({ And specify `src/middleware.ts` in `app.config.ts`: -```typescript {filename:app.config.ts} +```typescript {filename:app.config.ts} {7} +import { withSentry } from '@sentry/solidstart'; import { defineConfig } from '@solidjs/start/config'; -export default defineConfig({ - // ... - middleware: './src/middleware.ts', -}); +export default defineConfig( + withSentry({ + // other SolidStart config options... + middleware: './src/middleware.ts', + }) +); ``` If you previously added the `solidRouterBrowserTracingIntegration` integration to `Sentry.init` in `src/entry-client.tsx`, wrap your Solid Router with `withSentryRouterRouting`. This creates a higher order component, which will enable Sentry to collect navigation spans. -```tsx {filename:app.tsx} +```tsx {filename:app.tsx} {5,9,11} import { Router } from "@solidjs/router"; import { FileRoutes } from "@solidjs/start/router"; import { withSentryRouterRouting } from '@sentry/solidstart/solidrouter' @@ -96,13 +108,22 @@ export default function App() { ### Run your application -Add an `--import` flag to the `NODE_OPTIONS` environment variable wherever you run your application to import `public/instrument.server.mjs`. +Add an `--import` flag directly or to the `NODE_OPTIONS` environment variable wherever you run your application to import `.output/server/instrument.server.mjs `. For example, update your scripts in `package.json`. ```json {filename:package.json} { "scripts": { - "start": "NODE_OPTIONS='--import ./public/instrument.server.mjs' vinxi start", + "start:vinxi": "NODE_OPTIONS='--import ./.output/server/instrument.server.mjs ' vinxi start", + "start:node": "node --import ./.output/server/instrument.server.mjs .output/server/index.mjs" } } +``` + + + If you experience any issues during the server-side setup, read through the different installation methods + or check out Troubleshooting. + + +