Skip to content

Commit

Permalink
Add Remix wizard instructions (#7768)
Browse files Browse the repository at this point in the history 
Co-authored-by: Steven Eubank <47563310+smeubank@users.noreply.github.com>
Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>
Co-authored-by: Abhijeet Prasad <devabhiprasad@gmail.com>
Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>
Co-authored-by: Liza Mock <lizka920@gmail.com>
  • Loading branch information
@onurtemizkan @smeubank
@shanamatthews @AbhiPrasad @Lms24 @lizokm
6 people committed Sep 19, 2023
1 parent aa2c1d3 commit ee9023c
Show file tree
Hide file tree
Showing 3 changed files with 234 additions and 190 deletions.
187 changes: 2 additions & 185 deletions src/platform-includes/getting-started-config/javascript.remix.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,185 +1,2 @@
To use this SDK, initialize Sentry in your Remix entry points for both the client and server.

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.

The two configuration types are mostly the same, except that some configuration features, like Session Replay, only work in `entry.client.tsx`.

<SignInNote />

```typescript {tabTitle:Client} {filename: entry.client.tsx}
import { useLocation, useMatches } from "@remix-run/react";
import * as Sentry from "@sentry/remix";
import { useEffect } from "react";

Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [
new Sentry.BrowserTracing({
routingInstrumentation: Sentry.remixRouterInstrumentation(
useEffect,
useLocation,
useMatches
),
}),
// Replay is only available in the client
new Sentry.Replay(),
],

// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for performance monitoring.
// 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,
});
```

```typescript {tabTitle:Server} {filename: entry.server.tsx}
import { useLocation, useMatches } from "@remix-run/react";
import * as Sentry from "@sentry/remix";
import { useEffect } from "react";

Sentry.init({
dsn: "___PUBLIC_DSN___",

// Set tracesSampleRate to 1.0 to capture 100%
// of transactions for performance monitoring.
// We recommend adjusting this value in production
tracesSampleRate: 1.0,
});
```

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.

To catch React component errors (in Remix v1) and routing transactions, wrap your Remix root with `withSentry`.

<Note>

If you use the Remix `v2_errorBoundary` future flag, you must also configure a [v2 ErrorBoundary](#v2-errorboundary).

</Note>

```typescript {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);
```

You can disable or configure `ErrorBoundary` using a second parameter to `withSentry`.

```typescript
withSentry(App, {
wrapWithErrorBoundary: false,
});

// or

withSentry(App, {
errorBoundaryOptions: {
fallback: <p>An error has occurred</p>,
},
});
```

## Custom Express Server

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.

<Note>

`wrapExpressCreateRequestHandler` is available starting with version 7.11.0.

</Note>

```typescript {filename: server/index.ts}
import { wrapExpressCreateRequestHandler } from "@sentry/remix";
import { createRequestHandler } from "@remix-run/express";

// ...

const createSentryRequestHandler =
wrapExpressCreateRequestHandler(createRequestHandler);

// Use createSentryRequestHandler like you would with createRequestHandler
app.all("*", createSentryRequestHandler(/* ... */));
```

## Remix v2 features

_Available from SDK version 7.59.0_

[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).

### v2 ErrorBoundary

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.

```typescript {filename: root.tsx}
import { captureRemixErrorBoundaryError } from "@sentry/remix";

export const ErrorBoundary: V2_ErrorBoundaryComponent = () => {
const error = useRouteError();

captureRemixErrorBoundaryError(error);

return <div> ... </div>;
};
```

## v2 Server-side Errors

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.

```typescript {filename: entry.server.tsx}
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);
}
}
```

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).

<Note>

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.

</Note>
To complete your configuration, add <PlatformLink to="/configuration/options/">options</PlatformLink> to your `Sentry.init()` calls.
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.
26 changes: 21 additions & 5 deletions src/platform-includes/getting-started-install/javascript.remix.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,23 @@
```bash {tabTitle:npm}
npm install --save @sentry/remix
```
We recommend installing the SDK through our installation wizard:

```bash {tabTitle:Yarn}
yarn add @sentry/remix
```bash
npx @sentry/wizard@latest -i remix
```

The wizard will prompt you to log in to Sentry. It will then automatically do the following steps for you:

- create two files in the root directory of your project, `entry.client.tsx` and `entry.server.tsx` (if they don't already exist).
- add the default `Sentry.init()` for the client in `entry.client.tsx` and the server in `entry.server.tsx`.
- create `.sentryclirc` with an auth token to upload source maps (this file is automatically added to `.gitignore`).
- adjust your `build` script in `package.json` to automatically upload source maps to Sentry when you build your application.

If you use [Remix future flags](https://remix.run/docs/en/main/pages/api-development-strategy#current-future-flags), the wizard will instrument your application accordingly to support Remix v2 features.

After the wizard setup is completed, the SDK will automatically capture unhandled errors, and monitor performance.
You can also <PlatformLink to="/usage/">manually capture errors</PlatformLink>.

<Note>

If the wizard setup isn't working for you, you can <PlatformLink to="/manual-setup/">set up the SDK manually</PlatformLink>.

</Note>
Loading

1 comment on commit ee9023c

@vercel
Copy link

@vercel vercel bot commented on ee9023c Sep 19, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

sentry-docs – ./

sentry-docs-git-master.sentry.dev
docs.sentry.io
sentry-docs.sentry.dev

Please sign in to comment.