From ee4dd312f042c1a9487b96823baec364dbaa70ca Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 2 Oct 2026 11:23:07 +0200 Subject: [PATCH 1/3] docs(remix): Add the Remix 3 alpha setup page Co-Authored-By: Claude Fable 5.1 --- .../javascript/guides/remix/index.mdx | 4 +- .../javascript/guides/remix/remix-3.mdx | 219 ++++++++++++++++++ 2 files changed, 221 insertions(+), 2 deletions(-) create mode 100644 docs/platforms/javascript/guides/remix/remix-3.mdx diff --git a/docs/platforms/javascript/guides/remix/index.mdx b/docs/platforms/javascript/guides/remix/index.mdx index 80d7a6d795555..62be8b39c6f82 100644 --- a/docs/platforms/javascript/guides/remix/index.mdx +++ b/docs/platforms/javascript/guides/remix/index.mdx @@ -7,9 +7,9 @@ categories: - server --- - + -The current `@sentry/remix` SDK does not support [Remix 3](https://remix.run/blog/remix-3-beta-preview). If you're using Remix 3, the SDK may not work as expected. We're tracking support — check back for updates. +This guide covers Remix 2. Support for [Remix 3](https://remix.run/blog/remix-3-beta-preview) is in alpha and has its own setup, see Remix 3 (Alpha). diff --git a/docs/platforms/javascript/guides/remix/remix-3.mdx b/docs/platforms/javascript/guides/remix/remix-3.mdx new file mode 100644 index 0000000000000..eb2e0085d9a25 --- /dev/null +++ b/docs/platforms/javascript/guides/remix/remix-3.mdx @@ -0,0 +1,219 @@ +--- +title: Remix 3 (Alpha) +sidebar_order: 2 +description: "Learn how to set up Sentry in a Remix 3 app, upload source maps, and capture your first errors." +--- + + + +Support for Remix 3 is in alpha. The API can change in any release. It lives under the `@sentry/remix/v3` subpaths and is separate from the Remix 2 SDK documented on the other pages of this guide. Please [report issues](https://github.com/getsentry/sentry-javascript/issues/new/choose) you run into. + + + +Remix 3 has no build step: the asset server compiles browser modules per request. The SDK works with that instead of a bundler plugin. A module hook instruments the Remix server packages when Node imports them, and the asset server is instrumented so the browser modules it serves carry debug IDs. + + + +## Install + + + + + +Install the SDK. It requires `remix@3.0.0-rc.1` or later and Node 20.19 or later. + + + + +```bash {tabTitle:npm} +npm install @sentry/remix +``` + +```bash {tabTitle:yarn} +yarn add @sentry/remix +``` + +```bash {tabTitle:pnpm} +pnpm add @sentry/remix +``` + + + + + +## Configure the Server + +### Start With the Sentry Entry + + + + + +Start the app with `--import @sentry/remix/v3/node` instead of `--import remix/node-tsx`. The Sentry entry registers the module hook before your app's modules are imported, then loads `remix/node-tsx` for you. + + + + +```json {filename:package.json} +{ + "scripts": { + "start": "node --import @sentry/remix/v3/node server.ts" + } +} +``` + + + + + +### Initialize the SDK + + + + + +Call `init()` in your server entry. + +Each request gets a span named after the matched route pattern. Errors thrown in route handlers, middleware and the request listener are reported. Requests the client aborted are not, and neither are thrown responses with a status from 300 to 499. Pass `shouldHandleError` to `remixV3Integration()` to change that. + + + + +```ts {filename:server.ts} +import * as Sentry from "@sentry/remix/v3"; +import * as http from "node:http"; +import { createRequestListener } from "remix/node-fetch-server"; + +import { router } from "./app/router.ts"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + // Adjust this value in production, or use tracesSampler for greater control. + tracesSampleRate: 1.0, +}); + +http + .createServer(createRequestListener((request) => router.fetch(request))) + .listen(3000); +``` + + + + + +## Configure the Browser + +### Allow the SDK in the Asset Server + + + + + +Add `@sentry/remix` to `allowPackages` so the asset server can serve the SDK to the browser. + +There is no build step to inline environment variables, so use `define` to get the DSN into browser modules. The asset server substitutes these values when it compiles a module. + + + + +```ts {filename:app/assets.ts} +import { createAssetServer } from "remix/assets"; + +export const assets = createAssetServer({ + basePath: "/assets", + rootDir: process.cwd(), + allowFiles: ["app/**/public/**"], + allowPackages: ["remix", "@sentry/remix"], + scripts: { + define: { + "process.env.SENTRY_DSN": JSON.stringify(process.env.SENTRY_DSN), + }, + }, +}); +``` + + + + + +### Initialize the SDK + + + + + +Call `init()` in your browser entry, before `run()`. + +Page loads and navigations get a span each. Errors thrown while a component renders are reported; the Remix runtime does not rethrow those, so nothing else would see them. + + + + +```ts {filename:app/entry.ts} +import * as Sentry from "@sentry/remix/v3/client"; +import { run } from "remix/ui"; + +Sentry.init({ + dsn: process.env.SENTRY_DSN, + // Adjust this value in production, or use tracesSampler for greater control. + tracesSampleRate: 1.0, +}); + +export const app = run({ + async loadModule(moduleUrl, exportName) { + const mod = await import(moduleUrl); + return mod[exportName]; + }, +}); +``` + + + + + +## Upload Source Maps + + + + + +Browser modules served by the asset server carry debug IDs, so stack traces are symbolicated once the source maps are uploaded. Remix 3 has no build output to upload, so the SDK ships a command that compiles the browser module graph through your asset server and uploads it. + +Run it from your deploy pipeline, with the same code and configuration the server runs. The debug IDs are hashed from the compiled source, so what is uploaded matches what the running server serves. + +`--entry` is a browser entry path and can be repeated. The asset server is read from `./app/assets.ts` (export `assets`); set `--assets-module` and `--assets-export` if yours lives elsewhere. `--dry-run` compiles without uploading. + + + + +```bash +SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ \ +node --import @sentry/remix/v3/node \ + ./node_modules/.bin/sentry-remix-v3-upload-sourcemaps \ + --entry app/entry.ts \ + --org ___ORG_SLUG___ \ + --project ___PROJECT_SLUG___ \ + --release "$RELEASE" +``` + + + + + +Source maps are generated but hidden by default: modules do not reference them and `.map` requests are not served, so the source only reaches Sentry. Set `sourceMaps: "external"` on the asset server to serve them, or `sourceMaps: false` to turn them off. + +## Verify + +Start the app and throw an error from a route handler and from a browser component. Both should show up as issues in your project, the browser one with a readable stack trace once the source maps are uploaded. + + + +## Troubleshooting + +The SDK warns at startup when the instrumentation did not apply: + +``` +[Sentry] Remix 3 is not instrumented: @remix-run/fetch-router was imported before the Sentry module hook was registered. Start Node with `--import @sentry/remix/v3/node`. +``` + +Make sure the app starts with `--import @sentry/remix/v3/node` and not `--import remix/node-tsx`. A warning that names a version outside the supported range means the installed Remix release is newer than this SDK supports. From 82f4bce7faa365f9f9388e5a1abcdec6bdeb52e5 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 2 Oct 2026 13:38:21 +0200 Subject: [PATCH 2/3] docs(remix): Simplify the source map upload command Show the minimal invocation and move the optional flags into prose. The org, project and auth token are read from the environment and the release is proposed from git, so none of them need to be on the command line. Drop the troubleshooting section, that part was never shipped. Co-Authored-By: Claude Opus 5 --- .../javascript/guides/remix/remix-3.mdx | 24 ++++--------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/docs/platforms/javascript/guides/remix/remix-3.mdx b/docs/platforms/javascript/guides/remix/remix-3.mdx index eb2e0085d9a25..4c83f98b32ecc 100644 --- a/docs/platforms/javascript/guides/remix/remix-3.mdx +++ b/docs/platforms/javascript/guides/remix/remix-3.mdx @@ -181,25 +181,21 @@ Browser modules served by the asset server carry debug IDs, so stack traces are Run it from your deploy pipeline, with the same code and configuration the server runs. The debug IDs are hashed from the compiled source, so what is uploaded matches what the running server serves. -`--entry` is a browser entry path and can be repeated. The asset server is read from `./app/assets.ts` (export `assets`); set `--assets-module` and `--assets-export` if yours lives elsewhere. `--dry-run` compiles without uploading. - ```bash -SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ \ -node --import @sentry/remix/v3/node \ - ./node_modules/.bin/sentry-remix-v3-upload-sourcemaps \ - --entry app/entry.ts \ - --org ___ORG_SLUG___ \ - --project ___PROJECT_SLUG___ \ - --release "$RELEASE" +node --import @sentry/remix/v3/node ./node_modules/.bin/sentry-remix-v3-upload-sourcemaps --entry app/entry.ts ``` +The command reads `SENTRY_AUTH_TOKEN`, `SENTRY_ORG` and `SENTRY_PROJECT` from the environment, and proposes the release from your git history. Pass `--org`, `--project` or `--release` to set them yourself. + +`--entry` is a browser entry path and can be repeated. The asset server is read from `./app/assets.ts` (export `assets`); set `--assets-module` and `--assets-export` if yours lives elsewhere. `--dry-run` compiles without uploading. + Source maps are generated but hidden by default: modules do not reference them and `.map` requests are not served, so the source only reaches Sentry. Set `sourceMaps: "external"` on the asset server to serve them, or `sourceMaps: false` to turn them off. ## Verify @@ -207,13 +203,3 @@ Source maps are generated but hidden by default: modules do not reference them a Start the app and throw an error from a route handler and from a browser component. Both should show up as issues in your project, the browser one with a readable stack trace once the source maps are uploaded. - -## Troubleshooting - -The SDK warns at startup when the instrumentation did not apply: - -``` -[Sentry] Remix 3 is not instrumented: @remix-run/fetch-router was imported before the Sentry module hook was registered. Start Node with `--import @sentry/remix/v3/node`. -``` - -Make sure the app starts with `--import @sentry/remix/v3/node` and not `--import remix/node-tsx`. A warning that names a version outside the supported range means the installed Remix release is newer than this SDK supports. From bb267e16bc864b53000c867bfa9af06202bc0ce2 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Fri, 2 Oct 2026 13:49:44 +0200 Subject: [PATCH 3/3] docs(remix): Require --project for the Remix 3 upload command The command does not read the project from SENTRY_PROJECT. Co-Authored-By: Claude Fable 5.1 --- docs/platforms/javascript/guides/remix/remix-3.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/guides/remix/remix-3.mdx b/docs/platforms/javascript/guides/remix/remix-3.mdx index 4c83f98b32ecc..71f1be9fd6e87 100644 --- a/docs/platforms/javascript/guides/remix/remix-3.mdx +++ b/docs/platforms/javascript/guides/remix/remix-3.mdx @@ -185,14 +185,14 @@ Run it from your deploy pipeline, with the same code and configuration the serve ```bash -node --import @sentry/remix/v3/node ./node_modules/.bin/sentry-remix-v3-upload-sourcemaps --entry app/entry.ts +node --import @sentry/remix/v3/node ./node_modules/.bin/sentry-remix-v3-upload-sourcemaps --entry app/entry.ts --project ___PROJECT_SLUG___ ``` -The command reads `SENTRY_AUTH_TOKEN`, `SENTRY_ORG` and `SENTRY_PROJECT` from the environment, and proposes the release from your git history. Pass `--org`, `--project` or `--release` to set them yourself. +The command reads `SENTRY_AUTH_TOKEN` and `SENTRY_ORG` from the environment, and proposes the release from your git history. `--project` has to be passed. Pass `--org` or `--release` to set those yourself. `--entry` is a browser entry path and can be repeated. The asset server is read from `./app/assets.ts` (export `assets`); set `--assets-module` and `--assets-export` if yours lives elsewhere. `--dry-run` compiles without uploading.