[v9] Update docs for v9 (#12588)

Author: Luca Forstner

docs/platforms/javascript/common/configuration/integrations/debug.mdx

@@ -5,9 +5,9 @@ description: "Allows you to inspect the contents of a processed event and hint o
 
 {/* TODO(v9): Remove this page and all references to it */}
 
-<Alert title="Deprecation Notice">
+<Alert level="warning" title="Deprecation Notice">
 
-The `Debug` Integration is deprecated and will be removed in the next major version of the SDK.
+The `Debug` Integration was removed in version 9 of the SDK.
 To log outgoing events, we recommend using <PlatformLink to="/configuration/options/#beforeSend">beforeSend</PlatformLink> in `Sentry.init()`.
 
 </Alert>

docs/platforms/javascript/common/configuration/integrations/sessiontiming.mdx

@@ -5,9 +5,9 @@ description: "Adds session timing data to events. (deprecated)"
 
 {/* TODO(v9): Remove this page and all references to it */}
 
-<Alert title="Deprecation Notice">
+<Alert level="warning" title="Deprecation Notice">
 
-The `SessionTiming` Integration is deprecated and will be removed in the next major version of the SDK.
+The `SessionTiming` Integration was removed in version 9 of the SDK.
 To capture session durations alongside events, we recommend using <PlatformLink to="/enriching-events/context/">Context</PlatformLink>.
 
 </Alert>

docs/platforms/javascript/common/configuration/options.mdx

@@ -347,10 +347,9 @@ This function is called with a transaction event object, and can return a modifi
 
 <SdkOption name="beforeSendSpan" type='(span: SpanJSON) => SpanJSON | null'>
 
-<Include name="platforms/configuration/options/warn-before-send-span.mdx" />
-
-This function is called with a serialized span object, and can return a modified span object, or `null` to skip sending the span. This might be useful for manually stripping PII from spans or to remove individual spans from the span tree.
-This function is only called for child spans of the root span. If you want to modify or drop the root span, including all of its child spans, use [`beforeSendTransaction`](#beforeSendTransaction) instead.
+This function is called with a serialized span object, and can return a modified span object. This might be useful for manually stripping PII from spans.
+This function is only called for root spans and all children.
+If you want to drop the root span, including all of its child spans, use [`beforeSendTransaction`](#beforeSendTransaction) instead.
 
 </SdkOption>
 

docs/platforms/javascript/common/install/esm.mdx

@@ -74,19 +74,3 @@ Sentry.init({
   registerEsmLoaderHooks: false,
 });
 ```
-
-{/* TODO(v9): This will become the default behavior and registerEsmLoaderHooks will no longer accept an object. So I guess we should remove this section when v9 ships. */}
-
-If you are starting Sentry via `--import`, you can instruct `import-in-the-middle`
-to only wrap packages that Sentry specifically instruments. To do this, you can
-set the `onlyIncludeInstrumentedModules` to `true`:
-
-```javascript {tabTitle:ESM} {filename: instrument.mjs} {4-6}
-import * as Sentry from "@sentry/node";
-
-Sentry.init({
-  registerEsmLoaderHooks: {
-    onlyIncludeInstrumentedModules: true,
-  },
-});
-```

docs/platforms/javascript/common/install/esm__v8.x.mdx

@@ -0,0 +1,91 @@
+---
+title: ESM (MJS)
+sidebar_order: 10
+description: "Learn about running Sentry in an ESM application."
+supported:
+  - javascript.node
+  - javascript.connect
+  - javascript.express
+  - javascript.fastify
+  - javascript.hapi
+  - javascript.koa
+  - javascript.nestjs
+noindex: true
+---
+
+<Alert>
+  Are you unsure if you should use this installation method? Review our
+  [installation methods](../).
+</Alert>
+
+When running your application in ESM mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts.
+
+You need to create a file named `instrument.mjs` that imports and initializes Sentry:
+
+```javascript {tabTitle:ESM} {filename: instrument.mjs}
+import * as Sentry from "@sentry/node";
+
+// Ensure to call this before importing any other modules!
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+
+  // Add Tracing by setting tracesSampleRate
+  // We recommend adjusting this value in production
+  tracesSampleRate: 1.0,
+});
+```
+
+Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.js`, which contains your `Sentry.init()` code:
+
+```bash
+# Note: This is only available for Node v18.19.0 onwards.
+node --import ./instrument.mjs app.mjs
+```
+
+If it is not possible for you to pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows:
+
+```bash
+NODE_OPTIONS="--import ./instrument.mjs" npm run start
+```
+
+We do not support ESM in Node versions before 18.19.0.
+
+## Troubleshooting instrumentation
+
+By default, all packages are wrapped under the hood by
+[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to
+aid instrumenting them.
+
+If `import-in-the-middle` encounters problems wrapping a package, you may see
+syntax errors at runtime or logged errors in your console:
+
+```logs
+SyntaxError: The requested module '...' does not provide an export named '...'
+(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js'
+```
+
+To confirm that these errors are caused by `import-in-the-middle`,
+disable it by setting `registerEsmLoaderHooks` to false. Note, this will also
+disable tracing instrumentation:
+
+```javascript {tabTitle:ESM} {filename: instrument.mjs} {4}
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  registerEsmLoaderHooks: false,
+});
+```
+
+If you are starting Sentry via `--import`, you can instruct `import-in-the-middle`
+to only wrap packages that Sentry specifically instruments. To do this, you can
+set the `onlyIncludeInstrumentedModules` to `true`:
+
+```javascript {tabTitle:ESM} {filename: instrument.mjs} {4-6}
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  registerEsmLoaderHooks: {
+    onlyIncludeInstrumentedModules: true,
+  },
+});
+```

docs/platforms/javascript/common/migration/v8-to-v9.mdx

@@ -8,6 +8,14 @@ notSupported:
   - javascript.electron
 ---
 
+<PlatformSection supported={["javascript"]}>
+<Alert title="Using a framework?" level="info">
+
+Make sure to select your framework in the dropdown in the top left corner of the page.
+
+</Alert>
+</PlatformSection>
+
 Version 9 of the Sentry JavaScript SDK primarily introduces API cleanup and version support changes.
 
 This update contains behavioral changes that will not be caught by type checkers, linters, or tests, so we recommend carefully reading through the entire migration guide instead of relying on automatic tooling.

docs/platforms/javascript/common/troubleshooting/supported-browsers.mdx

@@ -16,6 +16,25 @@ notSupported:
   - javascript.nestjs
 ---
 
+Sentry's latest JavaScript SDKs require ES2020 compatibility. The minimum supported browser versions are:
+
+- Chrome 80
+- Edge 80
+- Safari 14, iOS Safari 14.4
+- Firefox 74
+- Opera 67
+- Samsung Internet 13.0
+
+In addition, the Sentry JavaScript SDKs require the `fetch` API to be available.
+If you need to support browser-like environments that do not have `fetch` available, you should include a polyfill for the fetch API.
+
+## Supporting earlier JavaScript versions
+
+The Sentry JavaScript SDK uses ES2020 syntax and functionality to provide the best possible user experience and lowest bundle size.
+If you want to support earlier versions, you need to transpile your code using a transpiler like Babel, SWC, or TypeScript, and add polyfills.
+
+## 8.x Browser support
+
 Sentry's JavaScript SDKs require ES2018 compatibility plus support for [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis). The minimum supported browser versions are:
 
 - Chrome 71
@@ -25,12 +44,6 @@ Sentry's JavaScript SDKs require ES2018 compatibility plus support for [`globalT
 - Opera 58
 - Samsung Internet 10
 
-In addition, the Sentry JavaScript SDKs require the `fetch` API to be available. If you need to support browser-like environments that do not have `fetch` available, you should include a polyfill for the fetch API.
-
-## Support for IE11 / ES5
-
-The Sentry JavaScript SDK uses ES2018 syntax and functionality to provide the best possible user experience and lowest bundle size. If you want to support IE11 (or other environments that do not support ES6), you need to transpile your code using a bundler like webpack, Vite, Rollup, etc and add polyfills for ES5 functionality.
-
 ## 7.x Browser support
 
 `7.x` of the Sentry JavaScript SDKs use ES6 syntax, along with a few other ES6+ language features, such as object spread. If you are down-compiling your code in order to target older browsers that don't support such syntax, you'll need to include the Sentry SDK in that process.

docs/platforms/javascript/guides/react/features/tanstack-router.mdx

@@ -3,9 +3,7 @@ title: TanStack Router
 description: "Learn about Sentry's TanStack Router integration."
 ---
 
-_(Available in version 8.7.0 and above)_
-
-TanStack Router support is included in the `@sentry/react` package since version `8.7.0` and is only compatible with version `1.34.5` of ` `@tanstack/router` and above.
+The TanStack Router integration is included in the `@sentry/react` package and is compatible with version `1.64.0` of `@tanstack/react-router` and above.
 
 <Alert title="Note">
 

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

@@ -36,7 +36,6 @@ pnpm add @sentry/remix
 
 To use this SDK, initialize Sentry in your Remix project for both the client and server.
 
-
 ### Client-side Configuration
 
 ```typescript {tabTitle:Client} {filename: entry.client.tsx} {"onboardingOptions": {"performance": "8-12,16-23", "session-replay": "13-14,24-28"}}
@@ -79,7 +78,7 @@ Sentry.init({
 
 To capture errors from [ErrorBoundary](https://remix.run/docs/en/main/route/error-boundary), you should define your own `ErrorBoundary` in `root.tsx` and use `Sentry.captureRemixErrorBoundaryError` inside of it. You can also create route-specific error capturing behavior by defining `ErrorBoundary` in your route components. The `ErrorBoundary` you define in `root.tsx` will be used as a fallback for all routes.
 
-```typescript {filename: root.tsx}
+```tsx {filename: root.tsx}
 import { captureRemixErrorBoundaryError } from "@sentry/remix";
 
 export const ErrorBoundary: V2_ErrorBoundaryComponent = () => {
@@ -91,14 +90,9 @@ export const ErrorBoundary: V2_ErrorBoundaryComponent = () => {
 };
 ```
 
-To catch React component errors (in Remix v1) and routing transactions (in all Remix versions), wrap your Remix root with `withSentry`.
-
-<Alert>
-
-If you use Remix v1 with the `v2_errorBoundary` future flag, you must also configure your `ErrorBoundary`.
-</Alert>
+To capture performance data, wrap your Remix root with `withSentry`.
 
-```typescript {filename: root.tsx}
+```tsx {filename: root.tsx}
 import {
   Links,
   LiveReload,
@@ -130,15 +124,9 @@ function App() {
 export default withSentry(App);
 ```
 
-<Alert>
-
-If you use Remix v2, `wrapWithErrorBoundary` is disabled by default. You still need to wrap your root component with `withSentry` to capture routing transactions.
-
-</Alert>
-
 You can disable or configure `ErrorBoundary` using a second parameter to `withSentry`.
 
-```typescript
+```tsx
 withSentry(App, {
   wrapWithErrorBoundary: false,
 });
@@ -152,7 +140,6 @@ withSentry(App, {
 });
 ```
 
-
 ### Server-side Configuration
 
 Create an instrumentation file (named here as `instrument.server.mjs`) in your project. Add your initialization code in this file for the server-side SDK.
@@ -169,18 +156,15 @@ Sentry.init({
   // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
   tracesSampleRate: 1.0,
 
-  // To use Sentry OpenTelemetry auto-instrumentation
-  // default: false
-  autoInstrumentRemix: true,
-
   // Optionally capture action formData attributes with errors.
   // This requires `sendDefaultPii` set to true as well.
   captureActionFormDataKeys: {
     key_x: true,
     key_y: true,
   },
+
   // To capture action formData attributes.
-  sendDefaultPii: true
+  sendDefaultPii: true,
 });
 ```
 
@@ -199,43 +183,29 @@ Sentry's Remix SDK will automatically record your [`action`](https://remix.run/d
 #### Server-side Errors
 
 To capture server-side errors automatically, instrument the [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function in your server entry point.
+Wrap your error handler with `wrapHandleErrorWithSentry` or use `sentryHandleError` to export as your `handleError` function:
 
-If you're using Sentry Remix SDK version `7.87.0` or higher, you can wrap your error handler with `wrapHandleErrorWithSentry` or use `sentryHandleError` to export as your `handleError` function.
-
-```typescript {filename: entry.server.tsx (@sentry/remix >= 7.87.0)}
+```typescript {filename: entry.server.tsx}
 import * as Sentry from "@sentry/remix";
 
-export const handleError = Sentry.wrapHandleErrorWithSentry((error, { request }) => {
-  // Custom handleError implementation
-});
+export const handleError = Sentry.wrapHandleErrorWithSentry(
+  (error, { request }) => {
+    // Custom handleError implementation
+  }
+);
 
 // Alternative: Use the Sentry utility function if you don't need to wrap a custom function
 export const handleError = Sentry.sentryHandleError;
 ```
 
-For SDK versions older than `7.87.0`, you can use `Sentry.captureRemixServerException` to capture errors inside `handleError`.
-
-```typescript {filename: entry.server.tsx (@sentry/remix < 7.87.0)}
-export function handleError(
-  error: unknown,
-  { request }: DataFunctionArgs
-): void {
-  if (error instanceof Error) {
-    Sentry.captureRemixServerException(error, "remix.server", request);
-  } else {
-    // Optionally capture non-Error objects
-    Sentry.captureException(error);
-  }
-}
-```
-
 ### Source Maps Upload
 
 To enable readable stack traces, <PlatformLink to="/sourcemaps">configure source maps upload</PlatformLink> for your production builds.
 
 After you've completed this setup, the SDK will automatically capture unhandled errors and promise rejections, and monitor performance. You can also [manually capture errors](/platforms/javascript/guides/remix/usage).
 
 ## Verify
+
 This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.
 
 <PlatformContent includePath="getting-started-verify" />
@@ -252,7 +222,7 @@ You can import your server instrumentation file at the top of your Express serve
 
 ```typescript {filename: server.ts}
 // import the Sentry instrumentation file before anything else.
-import './instrument.server.mjs';
+import "./instrument.server.mjs";
 // alternatively `require('./instrument.server.cjs')`
 
 // ...