Remix 3 (Alpha)
Learn how to set up Sentry in a Remix 3 app, upload source maps, and capture your first errors.
Alpha
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 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 the SDK. It requires Remix 3.0.0 or later and Node 20.19 or later.
npm install @sentry/remix
npm install @sentry/remix
yarn add @sentry/remix
pnpm add @sentry/remix
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.
package.json{
"scripts": {
"start": "node --import @sentry/remix/v3/node server.ts"
}
}
{
"scripts": {
"start": "node --import @sentry/remix/v3/node server.ts"
}
}
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.
server.tsimport * 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);
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);
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.
app/assets.tsimport { 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),
},
},
});
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),
},
},
});
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.
app/entry.tsimport * as Sentry from "@sentry/remix/v3/client";
import { run } from "remix/component";
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];
},
});
import * as Sentry from "@sentry/remix/v3/client";
import { run } from "remix/component";
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];
},
});
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.
node --import @sentry/remix/v3/node ./node_modules/.bin/sentry-remix-v3-upload-sourcemaps --entry app/entry.ts --project ___PROJECT_SLUG___
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. A project is required: pass --project or set SENTRY_PROJECT. 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.
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.
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.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").