remix manual quick start guide and small update to wizard QS guide

inventarSarah · inventarSarah · commit 20ef03197c7f · 2025-06-05T09:29:48.000+02:00
diff --git a/docs/platforms/javascript/guides/remix/index.mdx b/docs/platforms/javascript/guides/remix/index.mdx
@@ -36,11 +36,47 @@ This guide assumes that you enable all features and allow the wizard to create a
 
 </Expandable>
 
-## Step 2: Avoid Ad Blockers With Tunneling (Optional)
+## Step 2: Server-Side Performance Monitoring
+
+To capture performance data on the server side, wrap your Remix root component (`root.tsx`) with `withSentry`:
+
+```tsx {filename: root.tsx}
+import {
+  Links,
+  LiveReload,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+} from "@remix-run/react";
+
+import { withSentry } from "@sentry/remix";
+
+function App() {
+  return (
+    <html>
+      <head>
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <Outlet />
+        <ScrollRestoration />
+        <Scripts />
+        <LiveReload />
+      </body>
+    </html>
+  );
+}
+
+export default withSentry(App);
+```
+
+## Step 3: Avoid Ad Blockers With Tunneling (Optional)
 
 <PlatformContent includePath="getting-started-tunneling" />
 
-## Step 3: Verify Your Setup
+## Step 4: Verify Your Setup
 
 If you haven't tested your Sentry configuration yet, let's do it now. You can confirm that Sentry is working properly and sending data to your Sentry project by using the example page created by the installation wizard:
 
diff --git a/docs/platforms/javascript/guides/remix/manual-setup.mdx b/docs/platforms/javascript/guides/remix/manual-setup.mdx
@@ -1,24 +1,29 @@
 ---
 title: Manual Setup
 sidebar_order: 1
-description: "Learn how to set up the SDK manually."
+description: "Learn how to manually set up Sentry in your Remix app and capture your first errors."
 ---
 
-If you can't (or prefer not to) run the [automatic setup](/platforms/javascript/guides/remix/#install), you can follow the instructions below to configure your application.
-
-## Features
+<Alert type="info">
+  For the fastest setup, we recommend using the [wizard
+  installer](/platforms/javascript/guides/remix).
+</Alert>
 
-In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also analyze performance profiles from real users with [profiling](/product/explore/profiling/). Lastly, adding [session replay](/product/explore/session-replay/web/getting-started/) lets you get to the root of an error or performance issue faster by watching a video-like reproduction of a user session with.
+<PlatformContent includePath="getting-started-prerequisites" />
 
-Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
+## Step 1: Install
 
-## Install
+Choose the features you want to configure, and this guide will show you how:
 
 <OnboardingOptionButtons
-  options={["error-monitoring", "performance", "profiling", "session-replay"]}
+  options={["error-monitoring", "performance", "session-replay"]}
 />
 
-Get started by installing the Sentry Remix SDK:
+<PlatformContent includePath="getting-started-features-expandable" />
+
+### Install the Sentry SDK
+
+Run the command for your preferred package manager to add the Sentry SDK to your application:
 
 ```bash {tabTitle:npm}
 npm install @sentry/remix --save
@@ -32,11 +37,11 @@ yarn add @sentry/remix
 pnpm add @sentry/remix
 ```
 
-## Configure
+## Step 2: Configure
 
-To use this SDK, initialize Sentry in your Remix project for both the client and server.
+### Configure Client-Side Sentry
 
-### Client-side Configuration
+Create a client file `entry.client.tsx` in the `app` folder of your project if you don't have one already. In this file, import and initialize the Sentry SDK:
 
 ```typescript {tabTitle:Client} {filename: entry.client.tsx}
 import { useLocation, useMatches } from "@remix-run/react";
@@ -45,11 +50,11 @@ import { useEffect } from "react";
 
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
-  
+
   // Adds request headers and IP for users, for more info visit:
   // https://docs.sentry.io/platforms/javascript/guides/remix/configuration/options/#sendDefaultPii
   sendDefaultPii: true,
-  
+
   integrations: [
     // ___PRODUCT_OPTION_START___ performance
     Sentry.browserTracingIntegration({
@@ -89,12 +94,14 @@ Sentry.init({
 
 #### Remix ErrorBoundary
 
-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.
+To capture errors from your [ErrorBoundary](https://remix.run/docs/en/main/route/error-boundary), define it in `root.tsx` to act as a fallback for all routes or create route-specific error boundaries in your route components.
+
+In your `ErrorBoundary` component, use `Sentry.captureRemixErrorBoundaryError` to send the captured error to Sentry:
 
 ```tsx {filename: root.tsx}
 import { captureRemixErrorBoundaryError } from "@sentry/remix";
 
-export const ErrorBoundary: V2_ErrorBoundaryComponent = () => {
+export const ErrorBoundary = () => {
   const error = useRouteError();
 
   captureRemixErrorBoundaryError(error);
@@ -103,7 +110,9 @@ export const ErrorBoundary: V2_ErrorBoundaryComponent = () => {
 };
 ```
 
-To capture performance data, wrap your Remix root with `withSentry`.
+#### Performance Monitoring
+
+Wrap your Remix root component with `withSentry` to capture performance data:
 
 ```tsx {filename: root.tsx}
 import {
@@ -137,21 +146,21 @@ function App() {
 export default withSentry(App);
 ```
 
-### Server-side Configuration
+### Configure Server-Side Sentry
 
-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.
+Create an instrumentation file `instrument.server.mjs` in your project's root folder and initialize the Sentry SDK within it:
 
 ```typescript {tabTitle:Server} {filename: instrument.server.mjs}
 import * as Sentry from "@sentry/remix";
 
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
-  
+
   // Adds request headers and IP for users, for more info visit: and captures action formData attributes
   // https://docs.sentry.io/platforms/javascript/guides/remix/configuration/options/#sendDefaultPii
   sendDefaultPii: true,
   // ___PRODUCT_OPTION_START___ performance
-  
+
   // Set tracesSampleRate to 1.0 to capture 100%
   // of transactions for tracing.
   // We recommend adjusting this value in production
@@ -169,22 +178,34 @@ Sentry.init({
 });
 ```
 
-Then run your Remix server with:
+Then run your Remix server using the `--import` command line option and point it to this file to make sure the Sentry module loads before any other application code runs:
 
 ```bash
 NODE_OPTIONS='--import=./instrument.server.mjs' remix-serve build
 # or
 NODE_OPTIONS='--require=./instrument.server.cjs' remix-serve build
 ```
 
-If you use the Express server instead of the Remix built-in server, you can alternatively import your instrumentation file directly at the top of your server implementation. See the example [here](#custom-express-server).
+<Expandable title="Are you using Express server?">
+If you use the Express server instead of the built-in Remix server, you can import your instrumentation file directly at the top of your server implementation.
+
+```typescript {filename: server.ts}
+// import the Sentry instrumentation file before anything else.
+import "./instrument.server.mjs";
+// alternatively `require('./instrument.server.cjs')`
+
+// ...
+
+const app = express();
+
+// ...
+```
 
-Sentry's Remix SDK will automatically record your [`action`](https://remix.run/docs/en/main/route/action) and [`loader`](https://remix.run/docs/en/main/route/loader) transactions, as well as server-side errors. You can also initialize Sentry's database integrations, such as <Link to="/platforms/javascript/guides/node/configuration/integrations/prisma/">Prisma</Link>, to get spans for your database calls.
+</Expandable>
 
-#### Server-side Errors
+#### Capture 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:
+To automatically capture server-side errors, instrument the [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function in your server entry point (`entry.server.tsx`). You can wrap your custom error handler with `wrapHandleErrorWithSentry` or directly use `sentryHandleError`:
 
 ```typescript {filename: entry.server.tsx}
 import * as Sentry from "@sentry/remix";
@@ -199,56 +220,141 @@ export const handleError = Sentry.wrapHandleErrorWithSentry(
 export const handleError = Sentry.sentryHandleError;
 ```
 
-### Source Maps Upload
+<Alert level="success" title="Tip">
 
-To enable readable stack traces, <PlatformLink to="/sourcemaps">configure source maps upload</PlatformLink> for your production builds.
+Sentry's Remix SDK automatically records your [`action`](https://remix.run/docs/en/main/route/action) and [`loader`](https://remix.run/docs/en/main/route/loader) transactions for performance monitoring. You can also initialize Sentry's database integrations, such as [Prisma](/platforms/javascript/guides/node/configuration/integrations/prisma/), to get spans for your database calls.
 
-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).
+</Alert>
 
-## Verify
+## Step 3: Add Readable Stack Traces With Source Maps (Optional)
 
-This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.
+To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slug in your `vite.config.ts` file:
 
-<Alert>
+<Alert title="Not using Vite?">
+  Check our [Source Maps documentation](/platforms/remix/source-maps) for
+  alternative setup options.
+</Alert>
 
-  Errors triggered from within Browser DevTools are sandboxed, so will not trigger an error handler. Place the snippet directly in your code instead.
+```javascript {filename:vite.config.ts} {3, 10-17,20-23}
+import { defineConfig } from "vite";
+import { vitePlugin as remix } from "@remix-run/dev";
+import { sentryVitePlugin } from "@sentry/vite-plugin";
 
-</Alert>
+export default defineConfig({
+  plugins: [
+    remix({
+      // ... your Remix plugin options
+    }),
+    sentryVitePlugin({
+      // If you use .sentryclirc or environment variables,
+      // you don't need to specify these options
+      org: "___ORG_SLUG___",
+      project: "___PROJECT_SLUG___",
+      // store your auth token in an environment variable
+      authToken: process.env.SENTRY_AUTH_TOKEN,
+    }),
+  ],
 
-Then, throw an error in a `loader` or `action`.
+  build: {
+    sourcemap: true,
+    // ... rest of your Vite build options
+  },
+});
+```
 
-```typescript {filename:routes/error.tsx}
-export const action: ActionFunction = async ({ request }) => {
-  throw new Error("Sentry Error");
-};
+To keep your auth token secure, always store it in an environment variable instead of directly in your files:
+
+<OrgAuthTokenNote />
+
+```bash {filename:.env}
+SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
 ```
 
-<Alert>
+## Step 4: Avoid Ad Blockers With Tunneling (Optional)
 
-  Learn more about manually capturing an error or message in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
+<PlatformContent includePath="getting-started-tunneling" />
 
-</Alert>
+## Step 5: Verify Your Setup
 
-To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.
+Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
 
-<Alert>
+### Issues
 
-You can refer to [Remix Docs](https://remix.run/docs/en/main/guides/envvars#browser-environment-variables) to learn how to use your Sentry DSN with environment variables.
+To verify that Sentry captures errors and creates issues in your Sentry project, add a test button to one of your pages:
 
-</Alert>
+```javascript
+<button
+  type="button"
+  onClick={
+	  throw new Error("Sentry Example Frontend Error");
+  }
+>
+  <span>
+    Throw Sample Error
+  </span>
+</button>
+```
 
-## Custom Express Server
+<OnboardingOption optionId="performance" hideForThisOption>
+
+Open the page in a browser (for most Remix applications, this will be at localhost:3000) and click the button to trigger a frontend error.
+
+</OnboardingOption>
+
+<OnboardingOption optionId="performance">
+
+### Tracing
+
+To test your tracing configuration, update the previous code snippet by calling a non-existing route and starting a trace to measure the time it takes for the execution of your code:
+
+```javascript
+<button
+  type="button"
+  onClick={async () => {
+    await Sentry.startSpan(
+      {
+        name: "Example Frontend Span",
+        op: "test",
+      },
+      async () => {
+        const res = await fetch("/api/sentry-example-api");
+        if (!res.ok) {
+          throw new Error("Sentry Example Frontend Error");
+        }
+      }
+    );
+  }}
+>
+  <span>Throw Sample Error</span>
+</button>
+```
 
-You can import your server instrumentation file at the top of your Express server implementation.
+Open the page in a browser (for most Remix applications, this will be at localhost:3000) and click the button to trigger the frontend error and a trace.
 
-```typescript {filename: server.ts}
-// import the Sentry instrumentation file before anything else.
-import "./instrument.server.mjs";
-// alternatively `require('./instrument.server.cjs')`
+</OnboardingOption>
 
-// ...
+<PlatformContent includePath="getting-started-browser-sandbox-warning" />
 
-const app = express();
+### View Captured Data in Sentry
 
-// ...
-```
+Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear).
+
+<PlatformContent includePath="getting-started-verify-locate-data" />
+
+## Next Steps
+
+At this point, you should have integrated Sentry into your Remix application and should already be sending error and performance data to your Sentry project.
+
+Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:
+
+- Learn how to [manually capture errors](/platforms/javascript/guides/remix/usage/)
+- Continue to [customize your configuration](/platforms/javascript/guides/remix/configuration/)
+- Get familiar with [Sentry's product features](/product/) like tracing, insights, and alerts
+
+<Expandable permalink={false} title="Are you having problems setting up the SDK?">
+
+- If you encountered issues with the manual setup, try <PlatformLink to="/">our installation wizard</PlatformLink>
+- Find various topics in <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
+- [Get support](https://sentry.zendesk.com/hc/en-us/)
+
+</Expandable>
