feat: whyrating - initial project from turbostarter boilerplate
This commit is contained in:
Alejandro Gutiérrez
@@ -0,0 +1,161 @@
|
||||
---
|
||||
title: Overview
|
||||
description: Get started with web monitoring in TurboStarter.
|
||||
url: /docs/web/monitoring/overview
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
TurboStarter includes lightweight monitoring hooks so you can quickly answer: **what's failing**, **where it's failing**, and **who it's affecting**. Out of the box, the web app can report exceptions from both the client and the server, and it's designed to be easy to extend with your preferred provider.
|
||||
|
||||
## Capturing exceptions
|
||||
|
||||
Monitoring starts with capturing exceptions reliably in the places that matter most:
|
||||
|
||||
* **Client-side errors**: the Next.js App Router error boundary reports unexpected runtime errors so you get visibility without leaving users stuck on a broken screen.
|
||||
* **Server-side errors**: API failures (for example, Hono errors in production) can be reported with a stable, anonymous distinct id so you can spot recurring issues and correlate them with sessions.
|
||||
* **Manual reporting**: you can also report exceptions from your own `try/catch` blocks to add extra context around critical flows (payments, onboarding, imports, etc.).
|
||||
|
||||
<Tabs items={["Client-side", "Server-side"]}>
|
||||
<Tab value="Client-side">
|
||||
```tsx
|
||||
"use client";
|
||||
|
||||
import { captureException } from "@turbostarter/monitoring-web";
|
||||
|
||||
export default function ExampleComponent() {
|
||||
const handleClick = () => {
|
||||
try {
|
||||
/* some risky operation */
|
||||
} catch (error) {
|
||||
captureException(error);
|
||||
}
|
||||
};
|
||||
|
||||
return <button onClick={handleClick}>Trigger Exception</button>;
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="Server-side">
|
||||
```ts
|
||||
import { captureException } from "@turbostarter/monitoring-web/server";
|
||||
|
||||
try {
|
||||
/* do something */
|
||||
} catch (error) {
|
||||
captureException(error);
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Callout type="error" title="Ensure correct import!">
|
||||
Make sure to use the correct import for the `captureException` function. We're using the same name for both client and server monitoring, but they are different functions. For server-side, just add `/server` to the import path (`@turbostarter/monitoring-web/server`).
|
||||
|
||||
<Tabs items={["Client-side", "Server-side"]}>
|
||||
<Tab value="Client-side">
|
||||
```tsx
|
||||
import { captureException } from "@turbostarter/monitoring-web";
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="Server-side">
|
||||
```tsx
|
||||
// [!code word:server]
|
||||
import { captureException } from "@turbostarter/monitoring-web/server";
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
</Callout>
|
||||
|
||||
## Identifying users
|
||||
|
||||
Exception reports become dramatically more actionable once they're tied to a real user. TurboStarter automatically identifies signed-in users (based on the current auth session), which allows your monitoring provider to associate exceptions and sessions with a user profile.
|
||||
|
||||
If you want richer debugging, identify users with traits (like email, plan, or role) so you can filter and segment issues by the people impacted.
|
||||
|
||||
```tsx title="monitoring.tsx"
|
||||
"use client";
|
||||
|
||||
import { useEffect } from "react";
|
||||
import { identify } from "@turbostarter/monitoring-web";
|
||||
import { authClient } from "~/lib/auth/client";
|
||||
|
||||
export const MonitoringProvider = ({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode;
|
||||
}) => {
|
||||
const session = authClient.useSession();
|
||||
|
||||
useEffect(() => {
|
||||
if (session.isPending) {
|
||||
return;
|
||||
}
|
||||
|
||||
identify(session.data?.user ?? null);
|
||||
}, [session]);
|
||||
|
||||
return <>{children}</>;
|
||||
};
|
||||
```
|
||||
|
||||
<Callout title="Identifying users on the server" type="warn">
|
||||
On the server, there are no dedicated identification helper. Most providers that support user-level tracking expect you to pass an identifier or traits directly within the `captureException` call (for example, as a `userId` or similar property), so make sure to check your specific provider's documentation for the recommended way to include user information.
|
||||
</Callout>
|
||||
|
||||
## Providers
|
||||
|
||||
The starter implements multiple providers for managing monitoring. To learn more about each provider and how to configure them, see their respective sections:
|
||||
|
||||
<Cards>
|
||||
<Card title="Sentry" href="/docs/web/monitoring/sentry" />
|
||||
|
||||
<Card title="PostHog" href="/docs/web/monitoring/posthog" />
|
||||
</Cards>
|
||||
|
||||
Configuration and setup are handled for you via a unified API, making it easy to switch monitoring providers by just updating the exports. You can also add custom providers without disrupting any monitoring-related logic.
|
||||
|
||||
## Best practices
|
||||
|
||||
Below are some guidelines to keep monitoring useful, low-noise, and privacy-safe.
|
||||
|
||||
<Cards>
|
||||
<Card title="Capture actionable errors" className="shadow-none">
|
||||
Report unexpected exceptions and failed business-critical operations; avoid
|
||||
logging “expected” states (validation errors, user cancellations, missing
|
||||
optional data).
|
||||
</Card>
|
||||
|
||||
<Card title="Add context" className="shadow-none">
|
||||
Include what the user was doing (route/action), relevant IDs (request id,
|
||||
order id), and a clear message so you can reproduce and triage quickly.
|
||||
</Card>
|
||||
|
||||
<Card title="Identify users, but avoid PII" className="shadow-none">
|
||||
Identify with stable IDs; only attach traits that are necessary for
|
||||
debugging. Don’t send secrets or sensitive fields (tokens, passwords, raw
|
||||
payment details).
|
||||
</Card>
|
||||
|
||||
<Card title="Deduplicate and rate-limit" className="shadow-none">
|
||||
If a loop or retry can fire many times, guard your capture calls so you
|
||||
don’t spam your provider (and your budget).
|
||||
</Card>
|
||||
|
||||
<Card title="Separate environments" className="shadow-none">
|
||||
Keep dev/staging/prod isolated (separate projects or environment tags) so
|
||||
production alerts stay meaningful.
|
||||
</Card>
|
||||
|
||||
<Card title="Alert on symptoms that matter" className="shadow-none">
|
||||
Set alerts for spikes in error rate, degraded performance, and failures in
|
||||
critical flows (auth, checkout, billing webhooks), not for every single
|
||||
exception.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
Application monitoring helps you track errors, exceptions, and performance issues for better app reliability. With multiple provider support, you can quickly spot and resolve problems.
|
||||
|
||||
Focus on actionable errors, useful context, and user privacy to get the most value from your monitoring.
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: PostHog
|
||||
description: Learn how to setup PostHog as your web monitoring provider.
|
||||
url: /docs/web/monitoring/posthog
|
||||
---
|
||||
|
||||
# PostHog
|
||||
|
||||
[PostHog](https://posthog.com/) is a comprehensive product analytics platform that includes error tracking, session replay, feature flags, and more. 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, PostHog 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: PostHog account">
|
||||
To use PostHog as your monitoring provider, you need to have an account. You can create one [here](https://app.posthog.com/signup) or [self-host](https://posthog.com/docs/self-host) it.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="You can also use it for analytics!">
|
||||
PostHog is also one of pre-configured providers for [analytics](/docs/web/analytics/overview) in TurboStarter. You can learn more about it [here](/docs/web/analytics/configuration#posthog).
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
PostHog integrates seamlessly with TurboStarter, enabling you to monitor application errors and performance from development to production. By configuring PostHog 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 PostHog in your TurboStarter project.
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
### Create a project
|
||||
|
||||
First, you need to create a [project](https://app.posthog.com/project/settings) in PostHog. You can do it directly from your [dashboard](https://app.posthog.com) by clicking on the *New Project* button.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Activate PostHog as your monitoring provider
|
||||
|
||||
The monitoring provider to use is determined by the exports in `packages/monitoring/web` package. To activate PostHog 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:posthog]
|
||||
export * from "./posthog";
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="server.ts">
|
||||
```ts
|
||||
// [!code word:posthog]
|
||||
export * from "./posthog/server";
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab value="env.ts">
|
||||
```ts
|
||||
// [!code word:posthog]
|
||||
export * from "./posthog/env";
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
If you want to customize the provider, you can find its definition in `packages/monitoring/web/src/providers/posthog` directory.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Set environment variables
|
||||
|
||||
Based on your [project settings](https://app.posthog.com/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_POSTHOG_KEY="your-posthog-api-key"
|
||||
NEXT_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it! You can now start your app and see the errors and exceptions in your [PostHog dashboard](https://app.posthog.com/project/error_tracking).
|
||||
|
||||
|
||||
|
||||
Feel free to customize the configuration to your needs. For more information, please refer to the [PostHog documentation](https://posthog.com/docs/error-tracking/installation/nextjs).
|
||||
|
||||
<Cards>
|
||||
<Card title="Error tracking" href="https://posthog.com/docs/error-tracking" description="posthog.com" />
|
||||
|
||||
<Card title="Next.js error tracking installation" href="https://posthog.com/docs/error-tracking/installation/nextjs" description="posthog.com" />
|
||||
</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 PostHog), error reports include references to the original lines of your source code, not just the processed/minified output.
|
||||
</Callout>
|
||||
|
||||
PostHog can automatically provide readable stack traces for errors using source maps. The `@posthog/nextjs-config` package handles source map generation and upload automatically during the build process.
|
||||
|
||||
To start using source maps, install the package `@posthog/nextjs-config` in `apps/web/package.json` as a dependency.
|
||||
|
||||
```bash
|
||||
pnpm i @posthog/nextjs-config --filter web
|
||||
```
|
||||
|
||||
Next, extend your app's Next.js options by adding `withPostHogConfig` into the `next.config.ts` file:
|
||||
|
||||
```ts title="apps/web/next.config.ts"
|
||||
import { withPostHogConfig } from "@posthog/nextjs-config";
|
||||
|
||||
const config = {
|
||||
/* existing Next.js configuration options */
|
||||
};
|
||||
|
||||
export default withPostHogConfig(config, {
|
||||
personalApiKey: process.env.POSTHOG_API_KEY,
|
||||
envId: process.env.POSTHOG_ENV_ID,
|
||||
host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
|
||||
sourcemaps: {
|
||||
enabled: true, // Enable sourcemaps generation and upload
|
||||
project: "my-application", // Optional: Project name, defaults to repository name
|
||||
version: "1.0.0", // Optional: Release version, defaults to current git commit
|
||||
deleteAfterUpload: true, // Delete sourcemaps after upload, defaults to true
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Make sure you have set the following environment variables locally and in your deployment environment:
|
||||
|
||||
* `POSTHOG_ERROR_TRACKING_API_KEY` - Your [Personal API Key](https://app.posthog.com/settings/user-api-keys#variables) with write access on error tracking
|
||||
* `POSTHOG_PROJECT_ID` - Project ID from [project settings](https://app.posthog.com/settings/environment#variables)
|
||||
* `NEXT_PUBLIC_POSTHOG_HOST` - Your PostHog instance URL
|
||||
|
||||
<Callout type="warn" title="Verify source map generation, upload and injection">
|
||||
Before proceeding, confirm that source maps are being generated by checking for `.js.map` files in your `dist` directory. These are the symbol sets that will be used to unminify stack traces in PostHog.
|
||||
|
||||
Next, confirm that source maps are successfully uploaded to PostHog by checking the [symbol sets](https://app.posthog.com/project/settings/symbol-sets) section in your project settings.
|
||||
|
||||
Finally, confirm that the served files are injected with the correct source map comment in production. You can do this by inspecting your deployed app in browser dev tools and looking for a comment like this at the end of your JavaScript bundles:
|
||||
|
||||
```js
|
||||
//# chunkId=0197e6db-9a73-7b91-9e80-4e1b7158db5c
|
||||
```
|
||||
</Callout>
|
||||
|
||||
Once everything is set up, PostHog will provide you with detailed, easy-to-read error reports that link directly back to your original source code - even after your code has been bundled or minified. This makes diagnosing and fixing production issues much simpler.
|
||||
|
||||
<Cards>
|
||||
<Card title="What are source maps?" href="https://web.dev/articles/source-maps" description="web.dev" />
|
||||
|
||||
<Card title="Upload source maps for Next.js" href="https://posthog.com/docs/error-tracking/upload-source-maps/nextjs" description="posthog.com" />
|
||||
</Cards>
|
||||
@@ -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