docs(js): Create Remix manual quick start guide (#13928)

inventarSarah · chargome · web-flow · commit 9339aa1f7d9b · 2025-07-01T15:41:24.000+02:00
## DESCRIBE YOUR PR Converted the Remix Manual Setup guide into a Quick Start guide. I removed the "Profiling" onboarding option because it is not in the wizard. If we want to keep it in the quick start guide(s), we should create a separate GH issue to add Profiling to both guides as a manual step (updating the wizard installer itself would be best, though) There's also an update in the wizard QS guide: "Step 2: Server-Side Performance Monitoring" -> This is an important step that is included in the manual setup but not in the wizard. @chargome is inquiring about updating the wizard installer. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.):  - [ ] Other deadline:  - [x] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Charly Gomez <charly.gomez@sentry.io>
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", "user-feedback", "logs"]}
 />
 
-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({
@@ -100,12 +105,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);
@@ -114,7 +121,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 {
@@ -148,21 +157,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
@@ -185,22 +194,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?">
+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.
 
-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.
+```typescript {filename: server.(mjs|cjs)}
+// import the Sentry instrumentation file before anything else.
+import "./instrument.server.mjs";
+// alternatively `require('./instrument.server.cjs')`
 
-#### 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:
+const app = express();
+
+// ...
+```
+
+</Expandable>
+
+#### Capture Server-Side Errors
+
+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";
@@ -215,56 +236,143 @@ 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?">
 
-  Errors triggered from within Browser DevTools are sandboxed, so will not trigger an error handler. Place the snippet directly in your code instead.
+Check our [Source Maps documentation](/platforms/javascript/guides/remix/sourcemaps/) for
+alternative setup options.
 
 </Alert>
 
-Then, throw an error in a `loader` or `action`.
+```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";
 
-```typescript {filename:routes/error.tsx}
-export const action: ActionFunction = async ({ request }) => {
-  throw new Error("Sentry Error");
-};
+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,
+    }),
+  ],
+
+  build: {
+    sourcemap: true,
+    // ... rest of your Vite build options
+  },
+});
 ```
 
-<Alert>
+To keep your auth token secure, always store it in an environment variable instead of directly in your files:
 
-  Learn more about manually capturing an error or message in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
+<OrgAuthTokenNote />
 
-</Alert>
+```bash {filename:.env}
+SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
+```
 
-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.
+## Step 4: Avoid Ad Blockers With Tunneling (Optional)
 
-<Alert>
+<PlatformContent includePath="getting-started-tunneling" />
 
-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.
+## Step 5: Verify Your Setup
 
-</Alert>
+Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
 
-## Custom Express Server
+### Issues
 
-You can import your server instrumentation file at the top of your Express server implementation.
+To verify that Sentry captures errors and creates issues in your Sentry project, add a test button to one of your pages:
 
-```typescript {filename: server.ts}
-// import the Sentry instrumentation file before anything else.
-import "./instrument.server.mjs";
-// alternatively `require('./instrument.server.cjs')`
+```javascript
+<button
+  type="button"
+  onClick={
+	  throw new Error("Sentry Example Frontend Error");
+  }
+>
+  <span>
+    Throw Sample Error
+  </span>
+</button>
+```
 
-// ...
+<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>
+```
 
-const app = express();
+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.
 
-// ...
-```
+</OnboardingOption>
+
+<PlatformContent includePath="getting-started-browser-sandbox-warning" />
+
+### 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>
