From c943383a9c8c01bae716d0c2e1ff009919982eb5 Mon Sep 17 00:00:00 2001 From: Onur Temizkan Date: Mon, 4 Jul 2022 13:44:40 +0000 Subject: [PATCH 1/7] Add Remix SDK docs --- .../capture-error/javascript.remix.mdx | 11 ++ .../javascript.remix.mdx | 120 ++++++++++++++++++ .../javascript.remix.mdx | 7 + .../javascript.remix.mdx | 23 ++++ .../javascript.remix.mdx | 26 ++++ .../sourcemaps/generate/javascript.remix.mdx | 3 + .../sourcemaps/overview/javascript.remix.mdx | 15 +++ .../upload/primer/javascript.remix.mdx | 11 ++ .../common/sourcemaps/best-practices.mdx | 1 + .../common/sourcemaps/uploading/webpack.mdx | 2 + .../javascript/guides/remix/config.yml | 8 ++ 11 files changed, 227 insertions(+) create mode 100644 src/includes/capture-error/javascript.remix.mdx create mode 100644 src/includes/getting-started-config/javascript.remix.mdx create mode 100644 src/includes/getting-started-install/javascript.remix.mdx create mode 100644 src/includes/getting-started-primer/javascript.remix.mdx create mode 100644 src/includes/getting-started-verify/javascript.remix.mdx create mode 100644 src/includes/sourcemaps/generate/javascript.remix.mdx create mode 100644 src/includes/sourcemaps/overview/javascript.remix.mdx create mode 100644 src/includes/sourcemaps/upload/primer/javascript.remix.mdx create mode 100644 src/platforms/javascript/guides/remix/config.yml diff --git a/src/includes/capture-error/javascript.remix.mdx b/src/includes/capture-error/javascript.remix.mdx new file mode 100644 index 0000000000000..9e22fbe905ddf --- /dev/null +++ b/src/includes/capture-error/javascript.remix.mdx @@ -0,0 +1,11 @@ +You can pass an `Error` object to `captureException()` to get it captured as event. It's also possible to pass non-`Error` objects and strings, but be aware that the resulting events in Sentry may be missing a stacktrace. + +```typescript +import * as Sentry from "@sentry/remix"; + +try { + aFunctionThatMightFail(); +} catch (err) { + Sentry.captureException(err); +} +``` diff --git a/src/includes/getting-started-config/javascript.remix.mdx b/src/includes/getting-started-config/javascript.remix.mdx new file mode 100644 index 0000000000000..f21093c9682b6 --- /dev/null +++ b/src/includes/getting-started-config/javascript.remix.mdx @@ -0,0 +1,120 @@ +To use this SDK, initialize Sentry in your Remix entry points for both the client and server. + +```typescript {filename: entry.client.tsx} +import { useLocation, useMatches } from "@remix-run/react"; +import * as Sentry from "@sentry/remix"; +import { useEffect } from "react"; + +Sentry.init({ + dsn: "__DSN__", + tracesSampleRate: 1, + integrations: [ + new Sentry.BrowserTracing({ + routingInstrumentation: Sentry.remixRouterInstrumentation( + useEffect, + useLocation, + useMatches, + ), + }), + ], + // ... +}); +``` + +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 Prisma to get spans for your database calls. + +```typescript {filename: entry.server.tsx} +import { prisma } from "~/db.server"; + +import * as Sentry from "@sentry/remix"; + +Sentry.init({ + dsn: "__DSN__", + tracesSampleRate: 1, + integrations: [new Sentry.Integrations.Prisma({ client: prisma })], + // ... +}); +``` + +Also, wrap your Remix root, with Sentry's `ErrorBoundary` component to catch React component errors, and `withSentryRouteTracing` to get parameterized router transactions. + +```typescript {filename: root.tsx} +import { + Links, + LiveReload, + Meta, + Outlet, + Scripts, + ScrollRestoration, +} from "@remix-run/react"; + +import { ErrorBoundary, withSentryRouteTracing } from "@sentry/remix"; + +function App() { + return ( + + + + + + + + + + + + + + + ); +} + +export default withSentryRouteTracing(App); +``` + +Once you're 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). + +## Using Sentry DSN from environment variables + +To use Sentry DSN from environment variables on Remix client, you need to add it as a global in your `root` loader. + +```typescript {filename: root.tsx} +// ... + +type LoaderData = { + GLOBALS: string; +}; + +export const loader: LoaderFunction = async ({ request }) => { + return json({ + GLOBALS: JSON.stringify({ + SENTRY_DSN: process.env.SENTRY_DSN, + }), + }); +}; + +function App() { + const { GLOBALS } = useLoaderData() as LoaderData; + + return ( + // ... + ); +} +``` + +Then, use it as a global in your `entry.client.tsx` file. + +```typescript {filename: entry.client.tsx} +// ... + +Sentry.init({ + dsn: window.GLOBALS.SENTRY_DSN, + // ... +}); + +declare global { + interface Window { + GLOBALS: Record; + } +} +``` diff --git a/src/includes/getting-started-install/javascript.remix.mdx b/src/includes/getting-started-install/javascript.remix.mdx new file mode 100644 index 0000000000000..83b359837a2f6 --- /dev/null +++ b/src/includes/getting-started-install/javascript.remix.mdx @@ -0,0 +1,7 @@ +```bash {tabTitle:npm} +npm install --save @sentry/remix +``` + +```bash {tabTitle:yarn} +yarn add @sentry/remix +``` diff --git a/src/includes/getting-started-primer/javascript.remix.mdx b/src/includes/getting-started-primer/javascript.remix.mdx new file mode 100644 index 0000000000000..27bc70998b83b --- /dev/null +++ b/src/includes/getting-started-primer/javascript.remix.mdx @@ -0,0 +1,23 @@ + + +Sentry's Remix SDK enables automatic reporting of errors and exceptions, as well as the performance metrics for both client and server side operations. + + + + + +This SDK is still in experimental phase and is not yet ready for production use. + + + +Sentry's Remix SDK is introduced in version `7.4.0`. + +Features: + +- [Error Tracking](/product/issues/) with source maps for both JavaScript and TypeScript +- Events [enriched](/platforms/javascript/enriching-events/context/) with device data +- [Breadcrumbs](/platforms/javascript/enriching-events/breadcrumbs/) created for outgoing HTTP request with XHR and Fetch, and console logs +- [Release health](/product/releases/health/) for tracking crash-free users and sessions +- [Performance Monitoring](/product/performance/) for both the client and server. + +Under the hood, Remix SDK relies on our [React SDK](/platforms/javascript/guides/react/) on the frontend and [Node SDK](/platforms/node) on the backend, which makes all features available in those SDKs also available in this SDK. diff --git a/src/includes/getting-started-verify/javascript.remix.mdx b/src/includes/getting-started-verify/javascript.remix.mdx new file mode 100644 index 0000000000000..e65c194376487 --- /dev/null +++ b/src/includes/getting-started-verify/javascript.remix.mdx @@ -0,0 +1,26 @@ +Add a button to a frontend component that throws an error: + +```typescript {filename:routes/error.tsx} + +``` + + + +Errors triggered from within Browser DevTools are sandboxed, so will not trigger an error handler. Place the snippet directly in your code instead. + + + +And throw an error in a `loader` or `action`: + +```typescript {filename:routes/error.tsx} +export const action: ActionFunction = async ({ request }) => { + throw new Error("Sentry Error"); +}; +``` diff --git a/src/includes/sourcemaps/generate/javascript.remix.mdx b/src/includes/sourcemaps/generate/javascript.remix.mdx new file mode 100644 index 0000000000000..05ed267f66bee --- /dev/null +++ b/src/includes/sourcemaps/generate/javascript.remix.mdx @@ -0,0 +1,3 @@ +To generate source maps with your Remix project, you need to call `remix build` with the `--sourcemap` option. + +Please refer to the [Remix CLI docs](https://remix.run/docs/en/v1/other-api/dev#remix-cli) for more information. \ No newline at end of file diff --git a/src/includes/sourcemaps/overview/javascript.remix.mdx b/src/includes/sourcemaps/overview/javascript.remix.mdx new file mode 100644 index 0000000000000..b20d32edec747 --- /dev/null +++ b/src/includes/sourcemaps/overview/javascript.remix.mdx @@ -0,0 +1,15 @@ +Integrate your Remix project's source maps with Sentry using these steps: + +### 1: Generate Source Maps + +Remix can be configured to output source maps by Remix CLI. Learn more about how to generate sourcemaps with Remix [here](./generating/). + +### 2: Provide Source Maps to Sentry + +Source maps can be uploaded to Sentry by creating a release. Learn more about how to upload source maps [here](./uploading/). + + + +By default, if Sentry can't find the uploaded files it needs, it will attempt to download them from the URLs in the stacktrace. To disable this, turn off "Enable JavaScript source fetching" in either your organization's "Security & Privacy" settings or your project's general settings. + + diff --git a/src/includes/sourcemaps/upload/primer/javascript.remix.mdx b/src/includes/sourcemaps/upload/primer/javascript.remix.mdx new file mode 100644 index 0000000000000..d88f9b3a7e6b3 --- /dev/null +++ b/src/includes/sourcemaps/upload/primer/javascript.remix.mdx @@ -0,0 +1,11 @@ +On release, call `sentry-upload-sourcemaps` to upload source maps and create a release. + + + +`sentry-upload-sourcemaps` requires a valid `.sentryclirc` file to pick up your project ID, organization ID and token. You can create `.sentryclirc` file with necessary configuration, as documented on this [page](https://docs.sentry.io/product/cli/configuration/). + + + +To see more details on how to use the command, call `sentry-upload-sourcemaps --help`. + +For more advanced configuration, [directly use `sentry-cli` to upload source maps.](https://github.com/getsentry/sentry-cli). diff --git a/src/platforms/javascript/common/sourcemaps/best-practices.mdx b/src/platforms/javascript/common/sourcemaps/best-practices.mdx index 1c2e74ef73155..165208268326e 100644 --- a/src/platforms/javascript/common/sourcemaps/best-practices.mdx +++ b/src/platforms/javascript/common/sourcemaps/best-practices.mdx @@ -4,6 +4,7 @@ description: "Learn about best practices when integrating your source maps with sidebar_order: 7 notSupported: - javascript.nextjs + - javascript.remix --- diff --git a/src/platforms/javascript/common/sourcemaps/uploading/webpack.mdx b/src/platforms/javascript/common/sourcemaps/uploading/webpack.mdx index 58fc6667490e0..6500ad7e0dd37 100644 --- a/src/platforms/javascript/common/sourcemaps/uploading/webpack.mdx +++ b/src/platforms/javascript/common/sourcemaps/uploading/webpack.mdx @@ -2,6 +2,8 @@ title: Webpack description: "Upload your source maps to Sentry with our Webpack plugin." sidebar_order: 1 +notSupported: + - javascript.remix --- diff --git a/src/platforms/javascript/guides/remix/config.yml b/src/platforms/javascript/guides/remix/config.yml new file mode 100644 index 0000000000000..efa13a5f47dd2 --- /dev/null +++ b/src/platforms/javascript/guides/remix/config.yml @@ -0,0 +1,8 @@ +title: Remix +sdk: sentry.javascript.remix +fallbackPlatform: javascript +caseStyle: camelCase +supportLevel: production +categories: + - browser + - server From 23cae26a246e380b49c51b60e8562d89a23e6884 Mon Sep 17 00:00:00 2001 From: Onur Temizkan Date: Tue, 5 Jul 2022 08:59:49 +0000 Subject: [PATCH 2/7] Update `sentry-upload-sourcemaps` doca. --- src/includes/sourcemaps/upload/primer/javascript.remix.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/includes/sourcemaps/upload/primer/javascript.remix.mdx b/src/includes/sourcemaps/upload/primer/javascript.remix.mdx index d88f9b3a7e6b3..b36854934c542 100644 --- a/src/includes/sourcemaps/upload/primer/javascript.remix.mdx +++ b/src/includes/sourcemaps/upload/primer/javascript.remix.mdx @@ -1,11 +1,11 @@ -On release, call `sentry-upload-sourcemaps` to upload source maps and create a release. +On release, call `yarn sentry-upload-sourcemaps` to upload source maps and create a release. -`sentry-upload-sourcemaps` requires a valid `.sentryclirc` file to pick up your project ID, organization ID and token. You can create `.sentryclirc` file with necessary configuration, as documented on this [page](https://docs.sentry.io/product/cli/configuration/). +`sentry-upload-sourcemaps` requires either [`env` variables](https://docs.sentry.io/product/cli/configuration/#configuration-values) or a valid `.sentryclirc` file to pick up your project ID, organization ID and token. You can create `.sentryclirc` file with necessary configuration, as documented on this [page](https://docs.sentry.io/product/cli/configuration/). -To see more details on how to use the command, call `sentry-upload-sourcemaps --help`. +To see more details on how to use the command, call `yarn sentry-upload-sourcemaps --help`. For more advanced configuration, [directly use `sentry-cli` to upload source maps.](https://github.com/getsentry/sentry-cli). From 1fe9edccc26d3384dac928f94bab497edecf59b0 Mon Sep 17 00:00:00 2001 From: Onur Temizkan Date: Tue, 5 Jul 2022 09:21:25 +0000 Subject: [PATCH 3/7] Add notes about DSN and Prisma. --- .../javascript.remix.mdx | 52 ++++--------------- 1 file changed, 10 insertions(+), 42 deletions(-) diff --git a/src/includes/getting-started-config/javascript.remix.mdx b/src/includes/getting-started-config/javascript.remix.mdx index f21093c9682b6..119919a653c66 100644 --- a/src/includes/getting-started-config/javascript.remix.mdx +++ b/src/includes/getting-started-config/javascript.remix.mdx @@ -36,6 +36,12 @@ Sentry.init({ }); ``` + + +Learn more about Sentry's Prisma integration here. + + + Also, wrap your Remix root, with Sentry's `ErrorBoundary` component to catch React component errors, and `withSentryRouteTracing` to get parameterized router transactions. ```typescript {filename: root.tsx} @@ -74,47 +80,9 @@ export default withSentryRouteTracing(App); Once you're 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). -## Using Sentry DSN from environment variables - -To use Sentry DSN from environment variables on Remix client, you need to add it as a global in your `root` loader. - -```typescript {filename: root.tsx} -// ... - -type LoaderData = { - GLOBALS: string; -}; - -export const loader: LoaderFunction = async ({ request }) => { - return json({ - GLOBALS: JSON.stringify({ - SENTRY_DSN: process.env.SENTRY_DSN, - }), - }); -}; + + -function App() { - const { GLOBALS } = useLoaderData() as LoaderData; +You can refer to Remix Docs to learn how to use your Sentry DSN from environment variables. - return ( - // ... - ); -} -``` - -Then, use it as a global in your `entry.client.tsx` file. - -```typescript {filename: entry.client.tsx} -// ... - -Sentry.init({ - dsn: window.GLOBALS.SENTRY_DSN, - // ... -}); - -declare global { - interface Window { - GLOBALS: Record; - } -} -``` + \ No newline at end of file From 5dc791eae89c62ed515ad25d67cb73058b23d97e Mon Sep 17 00:00:00 2001 From: Onur Temizkan Date: Fri, 8 Jul 2022 13:51:24 +0100 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com> --- src/includes/capture-error/javascript.remix.mdx | 2 +- .../getting-started-config/javascript.remix.mdx | 10 +++++----- .../getting-started-primer/javascript.remix.mdx | 2 +- .../getting-started-verify/javascript.remix.mdx | 4 ++-- src/includes/sourcemaps/overview/javascript.remix.mdx | 6 +++--- .../sourcemaps/upload/primer/javascript.remix.mdx | 4 ++-- 6 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/includes/capture-error/javascript.remix.mdx b/src/includes/capture-error/javascript.remix.mdx index 9e22fbe905ddf..ec8e409c5fa44 100644 --- a/src/includes/capture-error/javascript.remix.mdx +++ b/src/includes/capture-error/javascript.remix.mdx @@ -1,4 +1,4 @@ -You can pass an `Error` object to `captureException()` to get it captured as event. It's also possible to pass non-`Error` objects and strings, but be aware that the resulting events in Sentry may be missing a stacktrace. +You can pass an `Error` object to `captureException()` to have it captured as an event. It's also possible to pass non-`Error` objects and strings, but be aware that the resulting events in Sentry may be missing a stack trace. ```typescript import * as Sentry from "@sentry/remix"; diff --git a/src/includes/getting-started-config/javascript.remix.mdx b/src/includes/getting-started-config/javascript.remix.mdx index 119919a653c66..30a0129dee515 100644 --- a/src/includes/getting-started-config/javascript.remix.mdx +++ b/src/includes/getting-started-config/javascript.remix.mdx @@ -21,7 +21,7 @@ Sentry.init({ }); ``` -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 Prisma to get spans for your database calls. +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 Prisma, to get spans for your database calls. ```typescript {filename: entry.server.tsx} import { prisma } from "~/db.server"; @@ -38,11 +38,11 @@ Sentry.init({ -Learn more about Sentry's Prisma integration here. +Learn more about Sentry's Prisma integration . -Also, wrap your Remix root, with Sentry's `ErrorBoundary` component to catch React component errors, and `withSentryRouteTracing` to get parameterized router transactions. +Also, wrap your Remix root with Sentry's `ErrorBoundary` component to catch React component errors, and `withSentryRouteTracing` to get parameterized router transactions. ```typescript {filename: root.tsx} import { @@ -78,11 +78,11 @@ function App() { export default withSentryRouteTracing(App); ``` -Once you're 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). +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). -You can refer to Remix Docs to learn how to use your Sentry DSN from environment variables. +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. \ No newline at end of file diff --git a/src/includes/getting-started-primer/javascript.remix.mdx b/src/includes/getting-started-primer/javascript.remix.mdx index 27bc70998b83b..6340b5336605d 100644 --- a/src/includes/getting-started-primer/javascript.remix.mdx +++ b/src/includes/getting-started-primer/javascript.remix.mdx @@ -18,6 +18,6 @@ Features: - Events [enriched](/platforms/javascript/enriching-events/context/) with device data - [Breadcrumbs](/platforms/javascript/enriching-events/breadcrumbs/) created for outgoing HTTP request with XHR and Fetch, and console logs - [Release health](/product/releases/health/) for tracking crash-free users and sessions -- [Performance Monitoring](/product/performance/) for both the client and server. +- [Performance Monitoring](/product/performance/) for both the client and server Under the hood, Remix SDK relies on our [React SDK](/platforms/javascript/guides/react/) on the frontend and [Node SDK](/platforms/node) on the backend, which makes all features available in those SDKs also available in this SDK. diff --git a/src/includes/getting-started-verify/javascript.remix.mdx b/src/includes/getting-started-verify/javascript.remix.mdx index e65c194376487..21f8a141d6acb 100644 --- a/src/includes/getting-started-verify/javascript.remix.mdx +++ b/src/includes/getting-started-verify/javascript.remix.mdx @@ -1,4 +1,4 @@ -Add a button to a frontend component that throws an error: +Add a button to a frontend component that throws an error. ```typescript {filename:routes/error.tsx}