|
1 | | -To use this SDK, initialize Sentry in your Remix entry points for both the client and server. |
2 | | - |
3 | | -Create two files in the root directory of your project, `entry.client.tsx` and `entry.server.tsx` (if they don't exist yet). In these files, add your initialization code for the client-side SDK and server-side SDK, respectively. |
4 | | - |
5 | | -The two configuration types are mostly the same, except that some configuration features, like Session Replay, only work in `entry.client.tsx`. |
6 | | - |
7 | | -<SignInNote /> |
8 | | - |
9 | | -```typescript {tabTitle:Client} {filename: entry.client.tsx} |
10 | | -import { useLocation, useMatches } from "@remix-run/react"; |
11 | | -import * as Sentry from "@sentry/remix"; |
12 | | -import { useEffect } from "react"; |
13 | | - |
14 | | -Sentry.init({ |
15 | | - dsn: "___PUBLIC_DSN___", |
16 | | - integrations: [ |
17 | | - new Sentry.BrowserTracing({ |
18 | | - routingInstrumentation: Sentry.remixRouterInstrumentation( |
19 | | - useEffect, |
20 | | - useLocation, |
21 | | - useMatches |
22 | | - ), |
23 | | - }), |
24 | | - // Replay is only available in the client |
25 | | - new Sentry.Replay(), |
26 | | - ], |
27 | | - |
28 | | - // Set tracesSampleRate to 1.0 to capture 100% |
29 | | - // of transactions for performance monitoring. |
30 | | - // We recommend adjusting this value in production |
31 | | - tracesSampleRate: 1.0, |
32 | | - |
33 | | - // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled |
34 | | - tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], |
35 | | - |
36 | | - // Capture Replay for 10% of all sessions, |
37 | | - // plus for 100% of sessions with an error |
38 | | - replaysSessionSampleRate: 0.1, |
39 | | - replaysOnErrorSampleRate: 1.0, |
40 | | -}); |
41 | | -``` |
42 | | - |
43 | | -```typescript {tabTitle:Server} {filename: entry.server.tsx} |
44 | | -import { useLocation, useMatches } from "@remix-run/react"; |
45 | | -import * as Sentry from "@sentry/remix"; |
46 | | -import { useEffect } from "react"; |
47 | | - |
48 | | -Sentry.init({ |
49 | | - dsn: "___PUBLIC_DSN___", |
50 | | - |
51 | | - // Set tracesSampleRate to 1.0 to capture 100% |
52 | | - // of transactions for performance monitoring. |
53 | | - // We recommend adjusting this value in production |
54 | | - tracesSampleRate: 1.0, |
55 | | -}); |
56 | | -``` |
57 | | - |
58 | | -Initialize Sentry in your entry point for the server to capture exceptions and get performance metrics for your [`action`](https://remix.run/docs/en/v1/api/conventions#action) and [`loader`](https://remix.run/docs/en/v1/api/conventions#loader) functions. You can also initialize Sentry's database integrations, such as <Link to="/platforms/node/performance/database/opt-in/#prisma-orm-integration">Prisma</Link>, to get spans for your database calls. |
59 | | - |
60 | | -To catch React component errors (in Remix v1) and routing transactions, wrap your Remix root with `withSentry`. |
61 | | - |
62 | | -<Note> |
63 | | - |
64 | | -If you use the Remix `v2_errorBoundary` future flag, you must also configure a [v2 ErrorBoundary](#v2-errorboundary). |
65 | | - |
66 | | -</Note> |
67 | | - |
68 | | -```typescript {filename: root.tsx} |
69 | | -import { |
70 | | - Links, |
71 | | - LiveReload, |
72 | | - Meta, |
73 | | - Outlet, |
74 | | - Scripts, |
75 | | - ScrollRestoration, |
76 | | -} from "@remix-run/react"; |
77 | | - |
78 | | -import { withSentry } from "@sentry/remix"; |
79 | | - |
80 | | -function App() { |
81 | | - return ( |
82 | | - <html> |
83 | | - <head> |
84 | | - <Meta /> |
85 | | - <Links /> |
86 | | - </head> |
87 | | - <body> |
88 | | - <Outlet /> |
89 | | - <ScrollRestoration /> |
90 | | - <Scripts /> |
91 | | - <LiveReload /> |
92 | | - </body> |
93 | | - </html> |
94 | | - ); |
95 | | -} |
96 | | - |
97 | | -export default withSentry(App); |
98 | | -``` |
99 | | - |
100 | | -You can disable or configure `ErrorBoundary` using a second parameter to `withSentry`. |
101 | | - |
102 | | -```typescript |
103 | | -withSentry(App, { |
104 | | - wrapWithErrorBoundary: false, |
105 | | -}); |
106 | | - |
107 | | -// or |
108 | | - |
109 | | -withSentry(App, { |
110 | | - errorBoundaryOptions: { |
111 | | - fallback: <p>An error has occurred</p>, |
112 | | - }, |
113 | | -}); |
114 | | -``` |
115 | | - |
116 | | -## Custom Express Server |
117 | | - |
118 | | -If you use a custom Express server in your Remix application, you should wrap your [`createRequestHandler` function](https://remix.run/docs/en/v1/other-api/adapter#createrequesthandler) manually with `wrapExpressCreateRequestHandler`. This is not required if you use the built-in Remix App Server. |
119 | | - |
120 | | -<Note> |
121 | | - |
122 | | -`wrapExpressCreateRequestHandler` is available starting with version 7.11.0. |
123 | | - |
124 | | -</Note> |
125 | | - |
126 | | -```typescript {filename: server/index.ts} |
127 | | -import { wrapExpressCreateRequestHandler } from "@sentry/remix"; |
128 | | -import { createRequestHandler } from "@remix-run/express"; |
129 | | - |
130 | | -// ... |
131 | | - |
132 | | -const createSentryRequestHandler = |
133 | | - wrapExpressCreateRequestHandler(createRequestHandler); |
134 | | - |
135 | | -// Use createSentryRequestHandler like you would with createRequestHandler |
136 | | -app.all("*", createSentryRequestHandler(/* ... */)); |
137 | | -``` |
138 | | - |
139 | | -## Remix v2 features |
140 | | - |
141 | | -_Available from SDK version 7.59.0_ |
142 | | - |
143 | | -[Remix v2](https://remix.run/docs/en/main/pages/v2) will introduce new features that require additional configuration to work with Sentry. These features are also available from version [1.17.0](https://github.com/remix-run/remix/releases/tag/remix%401.17.0) with [future flags](https://remix.run/docs/en/main/pages/api-development-strategy#current-future-flags). |
144 | | - |
145 | | -### v2 ErrorBoundary |
146 | | - |
147 | | -To capture errors from [v2 ErrorBoundary](https://remix.run/docs/en/main/route/error-boundary-v2), you should define your own `ErrorBoundary` in `root.tsx` and use `Sentry.captureRemixErrorBoundaryError` inside of it. You can also create route-specific error capturing behaviour by defining `ErrorBoundary` in your route components. The `ErrorBoundary` you define in `root.tsx` will be used as a fallback for all routes. |
148 | | - |
149 | | -```typescript {filename: root.tsx} |
150 | | -import { captureRemixErrorBoundaryError } from "@sentry/remix"; |
151 | | - |
152 | | -export const ErrorBoundary: V2_ErrorBoundaryComponent = () => { |
153 | | - const error = useRouteError(); |
154 | | - |
155 | | - captureRemixErrorBoundaryError(error); |
156 | | - |
157 | | - return <div> ... </div>; |
158 | | -}; |
159 | | -``` |
160 | | - |
161 | | -## v2 Server-side Errors |
162 | | - |
163 | | -When using `v2_errorBoundary` future flag, Sentry can't capture your server-side errors automatically. Instead, define a [`handleError`](https://remix.run/docs/en/main/file-conventions/entry.server#handleerror) function in your server entry point. Then, you should use `Sentry.captureRemixServerError` to capture errors in your server-side code. |
164 | | - |
165 | | -```typescript {filename: entry.server.tsx} |
166 | | -export function handleError( |
167 | | - error: unknown, |
168 | | - { request }: DataFunctionArgs |
169 | | -): void { |
170 | | - if (error instanceof Error) { |
171 | | - Sentry.captureRemixServerException(error, "remix.server", request); |
172 | | - } else { |
173 | | - // Optionally capture non-Error objects |
174 | | - Sentry.captureException(error); |
175 | | - } |
176 | | -} |
177 | | -``` |
178 | | - |
179 | | -Once you've done this set up, the SDK will automatically capture unhandled errors and promise rejections, and monitor performance in the client. You can also [manually capture errors](/platforms/javascript/guides/remix/usage). |
180 | | - |
181 | | -<Note> |
182 | | - |
183 | | -You can refer to [Remix Docs](https://remix.run/docs/en/v1/guides/envvars#browser-environment-variables) to learn how to use your Sentry DSN from environment variables. |
184 | | - |
185 | | -</Note> |
| 1 | +To complete your configuration, add <PlatformLink to="/configuration/options/">options</PlatformLink> to your `Sentry.init()` calls. |
| 2 | +Here, you'll also be able to set context data, which includes data about the <PlatformLink to="/enriching-events/identify-user/">user</PlatformLink>, <PlatformLink to="/enriching-events/tags/">tags</PlatformLink>, or even <PlatformLink to="/enriching-events/context/">arbitrary data</PlatformLink>, all of which will be added to every event sent to Sentry. |
0 commit comments