feat: whyrating - initial project from turbostarter boilerplate
This commit is contained in:
Alejandro Gutiérrez
@@ -0,0 +1,157 @@
|
||||
---
|
||||
title: Sentry
|
||||
description: Learn how to setup Sentry as your web monitoring provider.
|
||||
url: /docs/web/monitoring/sentry
|
||||
---
|
||||
|
||||
# Sentry
|
||||
|
||||
[Sentry](https://sentry.io/) is a popular error monitoring and performance tracking platform. It helps developers identify, diagnose, and fix issues in their applications by capturing and reporting errors and exceptions in real time.
|
||||
|
||||
With features like automatic error reporting, stack trace visualization, and user/session context, Sentry provides deep insight into how your application is behaving in production so you can quickly resolve problems and improve reliability.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: Sentry account">
|
||||
To use Sentry as your monitoring provider, you need to have an account. You can create one [here](https://sentry.io/signup).
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
Sentry integrates seamlessly with TurboStarter, enabling you to monitor application errors and performance from development to production. By configuring Sentry as your monitoring provider, you’ll be able to detect, track, and resolve issues proactively, leading to a more stable and reliable app.
|
||||
|
||||
Follow the simple setup instructions below to get started with Sentry in your TurboStarter project.
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
### Create a project
|
||||
|
||||
First, you need to create a [project](https://docs.sentry.io/product/projects/) in Sentry. You can do it directly from your [dashboard](https://sentry.io/settings/account/projects/) by clicking on the *Create Project* button.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Activate Sentry as your monitoring provider
|
||||
|
||||
The monitoring provider to use is determined by the exports in `packages/monitoring/web` package. To activate Sentry as your monitoring provider, you need to update the exports in:
|
||||
|
||||
<Tabs items={["index.ts", "server.ts", "env.ts"]}>
|
||||
<Tab value="index.ts">
|
||||
```ts
|
||||
// [!code word:sentry]
|
||||
export * from "./sentry";
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="server.ts">
|
||||
```ts
|
||||
// [!code word:sentry]
|
||||
export * from "./sentry/server";
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="env.ts">
|
||||
```ts
|
||||
// [!code word:sentry]
|
||||
export * from "./sentry/env";
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
If you want to customize the provider, you can find its definition in `packages/monitoring/web/src/providers/sentry` directory.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Set environment variables
|
||||
|
||||
Based on your [project settings](https://sentry.io/project/settings), fill the following environment variables in your `.env.local` file in `apps/web` directory and your deployment environment:
|
||||
|
||||
```dotenv title="apps/web/.env.local"
|
||||
NEXT_PUBLIC_SENTRY_DSN="your-sentry-dsn"
|
||||
NEXT_PUBLIC_PROJECT_ENVIRONMENT="your-project-environment"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Apply instrumentation to your app
|
||||
|
||||
Install the package `@sentry/nextjs` in `apps/web/package.json` as a dependency.
|
||||
|
||||
```bash
|
||||
pnpm i @sentry/nextjs --filter web
|
||||
```
|
||||
|
||||
Next, extend your app's Next.js options by adding `withSentryConfig` into the `next.config.ts` file:
|
||||
|
||||
```ts title="apps/web/next.config.ts"
|
||||
import { withSentryConfig } from "@sentry/nextjs";
|
||||
|
||||
const config = {
|
||||
/* existing Next.js configuration options */
|
||||
};
|
||||
|
||||
export default withSentryConfig(config, {
|
||||
org: "your-sentry-org",
|
||||
project: "your-sentry-project",
|
||||
});
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it! You can now start your app and see the errors and exceptions in your [Sentry dashboard](https://sentry.io/settings/account/projects/).
|
||||
|
||||
|
||||
|
||||
Feel free to customize the configuration to your needs. For more information, please refer to the [Sentry documentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/).
|
||||
|
||||
<Cards>
|
||||
<Card title="Quick Start" href="https://docs.sentry.io/platforms/javascript/guides/nextjs/" description="docs.sentry.io" />
|
||||
|
||||
<Card title="Manual Setup" href="https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/" description="docs.sentry.io" />
|
||||
</Cards>
|
||||
|
||||
## Uploading source maps
|
||||
|
||||
**Source maps** are files that map your minified or transpiled code (such as the JavaScript code generated by frameworks like Next.js) back to your original source code (for example, TypeScript or unbundled JavaScript). When your app is running in production, the code is often bundled and minified to improve performance, which makes stack traces and error messages hard to read and debug.
|
||||
|
||||
<Callout>
|
||||
With source maps enabled and uploaded to your monitoring provider (like Sentry), error reports include references to the original lines of your source code, not just the processed/minified output.
|
||||
</Callout>
|
||||
|
||||
Sentry can automatically provide readable stack traces for errors using source maps, requiring a [Sentry auth token](https://docs.sentry.io/account/auth-tokens/).
|
||||
|
||||
Update your `next.config.ts` file with the following options:
|
||||
|
||||
```ts title="apps/web/next.config.ts"
|
||||
import { withSentryConfig } from "@sentry/nextjs";
|
||||
|
||||
const config = {
|
||||
/* existing Next.js configuration options */
|
||||
};
|
||||
|
||||
export default withSentryConfig(config, {
|
||||
org: "your-sentry-org",
|
||||
project: "your-sentry-project",
|
||||
|
||||
// An auth token is required for uploading source maps.
|
||||
authToken: process.env.SENTRY_AUTH_TOKEN, // [!code ++]
|
||||
|
||||
// Upload a larger set of source maps for prettier stack traces (increases build time)
|
||||
widenClientFileUpload: true, // [!code ++]
|
||||
});
|
||||
```
|
||||
|
||||
Then, set the `SENTRY_AUTH_TOKEN` environment variable in your `.env.local` file in `apps/web` directory and your deployment environment:
|
||||
|
||||
```dotenv title="apps/web/.env.local"
|
||||
SENTRY_AUTH_TOKEN="your-sentry-auth-token"
|
||||
```
|
||||
|
||||
With these steps, your Sentry integration will give you clear, actionable error reports tied directly to your source code - even after bundling and minification. This makes it much easier to debug and resolve production issues.
|
||||
|
||||
Take a moment to test your setup and ensure source maps are correctly resolving stack traces in your [Sentry dashboard](https://sentry.io/settings/account/projects/). For deeper customization or additional troubleshooting, always consult the [official Sentry documentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/sourcemaps/).
|
||||
|
||||
<Cards>
|
||||
<Card title="What are source maps?" href="https://web.dev/articles/source-maps" description="web.dev" />
|
||||
|
||||
<Card title="Source maps" href="https://docs.sentry.io/platforms/javascript/guides/nextjs/sourcemaps/" description="docs.sentry.io" />
|
||||
</Cards>
|
||||
Reference in New Issue
Block a user