Manual Setup
Learn how to set up the SDK manually.
If you can't (or prefer not to) run the automatic setup, you can follow the instructions below to configure your application.
In addition to capturing errors, you can monitor interactions between multiple services or applications by enabling tracing. You can also analyze performance profiles from real users with profiling. Lastly, adding session replay lets you get to the root of an error or performance issue faster by watching a video-like reproduction of a user session with.
Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
Get started by installing the Sentry Remix SDK:
npm install @sentry/remix --save
To use this SDK, initialize Sentry in your Remix project for both the client and server.
entry.client.tsximport { useLocation, useMatches } from "@remix-run/react";
import * as Sentry from "@sentry/remix";
import { useEffect } from "react";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [
Sentry.browserTracingIntegration({
useEffect,
useLocation,
useMatches,
}),
// Replay is only available in the client
Sentry.replayIntegration(),
],
// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for tracing.
// We recommend adjusting this value in production
tracesSampleRate: 1.0,
// Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled
tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
// Capture Replay for 10% of all sessions,
// plus for 100% of sessions with an error
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
});
To capture errors from ErrorBoundary, 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.
root.tsximport { captureRemixErrorBoundaryError } from "@sentry/remix";
export const ErrorBoundary: V2_ErrorBoundaryComponent = () => {
const error = useRouteError();
captureRemixErrorBoundaryError(error);
return <div> ... </div>;
};
To catch React component errors (in Remix v1) and routing transactions (in all Remix versions), wrap your Remix root with withSentry.
If you use Remix v1 with the v2_errorBoundary future flag, you must also configure your ErrorBoundary.
root.tsximport {
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);
If you use Remix v2, wrapWithErrorBoundary is disabled by default. You still need to wrap your root component with withSentry to capture routing transactions.
You can disable or configure ErrorBoundary using a second parameter to withSentry.
withSentry(App, {
wrapWithErrorBoundary: false,
});
// or
withSentry(App, {
errorBoundaryOptions: {
fallback: <p>An error has occurred</p>,
},
});
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.
instrument.server.mjsimport * as Sentry from "@sentry/remix";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for tracing.
// We recommend adjusting this value in production
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
});
Then run your Remix server with:
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.
Sentry's Remix SDK will automatically record your action and loader transactions, as well as server-side errors. You can also initialize Sentry's database integrations, such as Prisma, to get spans for your database calls.
To capture server-side errors automatically, instrument the handleError function in your server entry point.
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.
entry.server.tsx (@sentry/remix >= 7.87.0)import * as Sentry from "@sentry/remix";
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.
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);
}
}
To enable readable stack traces, configure source maps upload 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.
This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.
routes/error.tsx<button
type="button"
onClick={() => {
throw new Error("Sentry Frontend Error");
}}
>
Throw error
</button>;
This snippet adds a button that throws an error in a component or page.
Errors triggered from within Browser DevTools are sandboxed, so will not trigger an error handler. Place the snippet directly in your code instead.
Then, throw an error in a loader or action.
routes/error.tsxexport const action: ActionFunction = async ({ request }) => {
throw new Error("Sentry Error");
};
You can refer to Remix Docs to learn how to use your Sentry DSN with environment variables.
You can import your server instrumentation file at the top of your Express server implementation.
server.ts// import the Sentry instrumentation file before anything else.
import "./instrument.server.mjs";
// alternatively `require('./instrument.server.cjs')`
// ...
const app = express();
// ...
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").