feat: whyrating - initial project from turbostarter boilerplate
This commit is contained in:
Alejandro Gutiérrez
@@ -0,0 +1,113 @@
|
||||
---
|
||||
title: Overview
|
||||
description: Get started with mobile monitoring in TurboStarter.
|
||||
url: /docs/mobile/monitoring/overview
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
TurboStarter ships with powerful, provider-agnostic monitoring helpers for the mobile app so you can answer the questions that matter in production: **what broke**, **on which screen**, and **which users were impacted**. It's designed for simplicity and extensibility, and works with multiple providers behind a single API.
|
||||
|
||||
## Capturing exceptions
|
||||
|
||||
On mobile, you'll usually want to report errors from a few key places:
|
||||
|
||||
* **UI/runtime crashes**: unexpected JS errors that would otherwise blank the screen or break navigation.
|
||||
* **Async work**: background tasks, effects, and data fetching where failures are easy to miss.
|
||||
* **Manual reporting**: wrap critical flows (auth, purchases, sync, deep-links) with `try/catch` so you can attach context when things go wrong.
|
||||
|
||||
```tsx
|
||||
import { Pressable, Text } from "react-native";
|
||||
import { captureException } from "@turbostarter/monitoring-mobile";
|
||||
|
||||
export default function ExampleComponent() {
|
||||
const handleClick = () => {
|
||||
try {
|
||||
/* some risky operation */
|
||||
} catch (error) {
|
||||
captureException(error);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<Pressable onPress={handleClick}>
|
||||
<Text>Trigger Exception</Text>
|
||||
</Pressable>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
<Callout type="warn" title="JS exceptions vs native crashes">
|
||||
`try/catch` (and most JS error handlers) can only see JavaScript exceptions. Native crashes (for example, a hard crash in a native module) typically require provider-specific native setup to capture crash reports. Use the provider pages below for platform details.
|
||||
</Callout>
|
||||
|
||||
## Identifying users
|
||||
|
||||
Error reports become much more actionable once they're tied to a signed-in user. TurboStarter supports identifying the current user after the auth session resolves, so your monitoring provider can associate errors with a stable user profile (without you plumbing this through every capture call).
|
||||
|
||||
If you want richer filtering, pass non-sensitive traits (plan, role, locale) depending on what your provider supports.
|
||||
|
||||
```tsx title="monitoring.tsx"
|
||||
import { useEffect } from "react";
|
||||
import { identify } from "@turbostarter/monitoring-mobile";
|
||||
import { authClient } from "~/lib/auth";
|
||||
|
||||
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="Keep user data minimal" type="error">
|
||||
Identify users with **stable IDs** and only the traits you need for debugging. Avoid sending PII or secrets (tokens, raw emails, payment details) unless you've explicitly decided it's acceptable for your monitoring provider and compliance requirements.
|
||||
</Callout>
|
||||
|
||||
## Providers
|
||||
|
||||
TurboStarter can report through different monitoring providers while keeping your app code consistent. Choose a provider (or swap later) by updating the exports/config in the monitoring package.
|
||||
|
||||
<Cards>
|
||||
<Card title="Sentry" href="/docs/mobile/monitoring/sentry" />
|
||||
|
||||
<Card title="PostHog" href="/docs/mobile/monitoring/posthog" />
|
||||
</Cards>
|
||||
|
||||
## Recommended practices
|
||||
|
||||
<Cards>
|
||||
<Card title="Report what you'd actually act on" className="shadow-none">
|
||||
Prioritize crashes, failed network calls that break a flow, and unexpected
|
||||
states. Skip noisy “expected” errors (validation, user cancellations).
|
||||
</Card>
|
||||
|
||||
<Card title="Attach useful context" className="shadow-none">
|
||||
Include the screen/route, the action the user took, and relevant IDs
|
||||
(request id, order id). Mobile issues are often device- or version-specific,
|
||||
so make sure app version/build info is included by your provider.
|
||||
</Card>
|
||||
|
||||
<Card title="Guard against loops" className="shadow-none">
|
||||
If an effect or retry path can fire repeatedly, debounce or dedupe your
|
||||
capture calls so you don't spam reports (or exceed quotas).
|
||||
</Card>
|
||||
|
||||
<Card title="Separate dev/staging/prod" className="shadow-none">
|
||||
Keep environments isolated so test devices don't pollute production signal.
|
||||
Tag builds/releases so you can correlate spikes with deployments.
|
||||
</Card>
|
||||
</Cards>
|
||||
|
||||
With solid capture + identification in place, mobile monitoring becomes a feedback loop: you can spot regressions quickly, understand who they affect, and validate fixes by release.
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: PostHog
|
||||
description: Learn how to setup PostHog as your mobile monitoring provider.
|
||||
url: /docs/mobile/monitoring/posthog
|
||||
---
|
||||
|
||||
# PostHog
|
||||
|
||||
[PostHog](https://posthog.com/) is a product analytics platform that can also help with monitoring via error tracking and session replay. On mobile, it's especially useful when you want to connect **what went wrong** with **what the user did** right before it happened.
|
||||
|
||||
TurboStarter keeps monitoring provider selection behind a unified API, so you can route captures to PostHog without changing your app code.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: PostHog account">
|
||||
You'll need a PostHog account ([cloud](https://app.posthog.com/signup) or [self-hosted](https://posthog.com/docs/self-host)) to use it as your monitoring provider.
|
||||
</Callout>
|
||||
|
||||
<Callout type="info" title="You can also use it for analytics!">
|
||||
PostHog is one of the preconfigured analytics providers for mobile apps. If you want product analytics (events, screens, funnels), see [analytics overview](/docs/mobile/analytics/overview) and the [PostHog configuration](/docs/mobile/analytics/configuration#posthog).
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
PostHog makes it easy to monitor your mobile app for errors and issues, giving you full visibility into when things go wrong. With TurboStarter, you can enable PostHog-based monitoring in just a few steps, sending errors and related user actions to your PostHog dashboard for debugging and product improvement.
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
### Create a project
|
||||
|
||||
Create a new PostHog [project](https://app.posthog.com/project/settings) for your mobile app. You can do this from the [PostHog dashboard](https://app.posthog.com) using the *New Project* action.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Activate PostHog as your monitoring provider
|
||||
|
||||
TurboStarter chooses the mobile monitoring provider through exports in `packages/monitoring/mobile`. To route monitoring events to PostHog, export the PostHog implementation from the package entrypoint:
|
||||
|
||||
```ts title="index.ts"
|
||||
// [!code word:posthog]
|
||||
export * from "./posthog";
|
||||
export * from "./posthog/env";
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Set environment variables
|
||||
|
||||
Add your PostHog project key (and host, if you're not using the default cloud region) to your mobile app env. Set these locally and in your build environment (for example, in your [EAS build profile](/docs/mobile/publishing/checklist#environment-variables)):
|
||||
|
||||
```dotenv title="apps/mobile/.env.local"
|
||||
EXPO_PUBLIC_POSTHOG_KEY="your-posthog-project-api-key"
|
||||
EXPO_PUBLIC_POSTHOG_HOST="https://us.i.posthog.com"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
That's it - launch the app, trigger an error, and confirm events are arriving in your PostHog project.
|
||||
|
||||
|
||||
|
||||
If you want to go beyond basic capture (session replay, feature flags, richer device/session context), follow [PostHog's React Native setup guidance](https://posthog.com/docs/error-tracking/installation/react-native).
|
||||
|
||||
<Cards>
|
||||
<Card title="Error tracking" href="https://posthog.com/docs/error-tracking" description="posthog.com" />
|
||||
|
||||
<Card title="React Native error tracking installation" href="https://posthog.com/docs/error-tracking/installation/react-native" description="posthog.com" />
|
||||
</Cards>
|
||||
|
||||
## Uploading source maps
|
||||
|
||||
**Source maps** map the bundled/minified JavaScript running on devices back to your original source code. Without them, mobile stack traces are often hard to read and difficult to action.
|
||||
|
||||
<Callout>
|
||||
With source maps uploaded to PostHog, error reports can be symbolicated so stack traces point to the real files and line numbers from your project.
|
||||
</Callout>
|
||||
|
||||
PostHog's React Native source maps flow has two main parts:
|
||||
|
||||
* **Inject debug IDs** into the bundle during bundling (Metro)
|
||||
* **Upload source maps** during your iOS/Android build (or via CLI in CI)
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
### Install and authenticate the PostHog CLI
|
||||
|
||||
Install the CLI globally:
|
||||
|
||||
```bash
|
||||
npm install -g @posthog/cli
|
||||
```
|
||||
|
||||
Then authenticate:
|
||||
|
||||
```bash
|
||||
posthog-cli login
|
||||
```
|
||||
|
||||
If you're running in CI, you can authenticate with environment variables instead:
|
||||
|
||||
```dotenv
|
||||
POSTHOG_CLI_HOST="https://us.posthog.com"
|
||||
POSTHOG_CLI_ENV_ID="your-posthog-project-id"
|
||||
POSTHOG_CLI_TOKEN="your-personal-api-key"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Inject debug IDs with Metro
|
||||
|
||||
Automatic injection relies on Expo's debug ID support. Update `metro.config.js` to use PostHog's Expo config:
|
||||
|
||||
```js title="metro.config.js"
|
||||
const { getPostHogExpoConfig } = require("posthog-react-native/metro");
|
||||
|
||||
const config = getPostHogExpoConfig(__dirname);
|
||||
|
||||
module.exports = config;
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Upload source maps during builds
|
||||
|
||||
If you can use the Expo plugin (recommended for managed EAS builds), add the plugin to your Expo config:
|
||||
|
||||
```ts title="app.config.ts"
|
||||
export default ({ config }: ConfigContext): ExpoConfig => ({
|
||||
...config,
|
||||
plugins: ["posthog-react-native/expo"],
|
||||
});
|
||||
```
|
||||
|
||||
If you can't use the Expo plugin, PostHog also supports wiring uploads directly into:
|
||||
|
||||
* **Android**: your Gradle build (`android/app/build.gradle`)
|
||||
* **iOS**: your Xcode “Bundle React Native code and images” build phase
|
||||
|
||||
Follow the [official PostHog instructions](https://posthog.com/docs/error-tracking/upload-source-maps/react-native) for the exact snippets for each platform.
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Verify uploads in PostHog
|
||||
|
||||
After a release build, confirm your symbol sets are present in [PostHog project error tracking dashboard](https://app.posthog.com/settings/project-error-tracking#error-tracking-symbol-sets) and then trigger a test error to ensure stack traces are resolving as expected.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
With debug IDs injected and source maps uploaded, PostHog can symbolicate React Native errors so stack traces point back to your original source files. If traces still look minified, double-check that you're testing a release build and that the latest symbol sets are present in your project settings.
|
||||
|
||||
<Cards>
|
||||
<Card title="What are source maps?" href="https://web.dev/articles/source-maps" description="web.dev" />
|
||||
|
||||
<Card title="Upload source maps for React Native" href="https://posthog.com/docs/error-tracking/upload-source-maps/react-native" description="posthog.com" />
|
||||
</Cards>
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: Sentry
|
||||
description: Learn how to setup Sentry as your mobile monitoring provider.
|
||||
url: /docs/mobile/monitoring/sentry
|
||||
---
|
||||
|
||||
# Sentry
|
||||
|
||||
[Sentry](https://sentry.io/) is a popular error monitoring platform that captures crashes and exceptions from production devices and helps you debug them with stack traces, breadcrumbs, and user context.
|
||||
|
||||
TurboStarter's mobile monitoring layer is provider-agnostic, but Sentry is a great default when you want reliable crash reporting plus readable stack traces in release builds.
|
||||
|
||||
<Callout type="warn" title="Prerequisite: Sentry account">
|
||||
To use Sentry, create an [account in Sentry](https://sentry.io/signup) first.
|
||||
</Callout>
|
||||
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
TurboStarter integrates effortlessly with Sentry, so you can capture application errors and analyze performance from development through production. Setting up Sentry as your provider lets you quickly find and fix issues, contributing to a more robust and dependable app.
|
||||
|
||||
Follow the steps below to integrate Sentry with your TurboStarter project.
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
### Create a project
|
||||
|
||||
Begin by creating a [project](https://docs.sentry.io/product/projects/) in Sentry. You can set this up from your [dashboard](https://sentry.io/settings/account/projects/) by clicking 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/mobile` package. To activate Sentry as your monitoring provider, you need to update the exports in:
|
||||
|
||||
```ts title="index.ts"
|
||||
// [!code word:sentry]
|
||||
export * from "./sentry";
|
||||
export * from "./sentry/env";
|
||||
```
|
||||
|
||||
If you want to customize the provider, you can find its definition in `packages/monitoring/mobile/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/mobile` directory and your deployment environment (e.g. [EAS build profile](/docs/mobile/publishing/checklist#environment-variables)):
|
||||
|
||||
```dotenv title="apps/mobile/.env.local"
|
||||
EXPO_PUBLIC_SENTRY_DSN="your-sentry-dsn"
|
||||
EXPO_PUBLIC_PROJECT_ENVIRONMENT="your-project-environment"
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### Wrap your app
|
||||
|
||||
Install the Sentry React Native SDK in the `mobile` workspace.
|
||||
|
||||
```bash
|
||||
pnpm i @sentry/react-native --filter mobile
|
||||
```
|
||||
|
||||
And then wrap the root component of your application with Sentry.wrap:
|
||||
|
||||
```tsx title="app/_layout.tsx"
|
||||
import * as Sentry from "@sentry/react-native";
|
||||
|
||||
export default Sentry.wrap(RootLayout);
|
||||
```
|
||||
|
||||
<Callout>
|
||||
TurboStarter initializes the SDK for you based on env + provider exports; you only need to wrap the root component.
|
||||
</Callout>
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
You're all set! Start your app and view any errors or exceptions directly in your [Sentry dashboard](https://sentry.io/settings/account/projects/).
|
||||
|
||||
|
||||
|
||||
You can tailor the setup further if needed. For more details, refer to the [official Sentry documentation](https://docs.sentry.io/platforms/react-native/features/).
|
||||
|
||||
<Cards>
|
||||
<Card title="Quick Start" href="https://docs.sentry.io/platforms/react-native/" description="docs.sentry.io" />
|
||||
|
||||
<Card title="Manual Setup" href="https://docs.sentry.io/platforms/react-native/manual-setup/" description="docs.sentry.io" />
|
||||
</Cards>
|
||||
|
||||
## Uploading source maps
|
||||
|
||||
Readable stack traces in Sentry require uploading source maps for release builds. For Expo projects, Sentry recommends enabling **two pieces**:
|
||||
|
||||
* the **Sentry Expo config plugin** (uploads during native builds)
|
||||
* the **Sentry Metro plugin** (adds debug IDs so bundles and source maps match)
|
||||
|
||||
### Add the Sentry Expo plugin
|
||||
|
||||
Add `@sentry/react-native/expo` plugin to your Expo config (`app.config.ts`):
|
||||
|
||||
```ts title="app.config.ts"
|
||||
export default ({ config }: ConfigContext): ExpoConfig => ({
|
||||
...config,
|
||||
plugins: [
|
||||
[
|
||||
"@sentry/react-native/expo",
|
||||
{
|
||||
url: "https://sentry.io/",
|
||||
project: "your-sentry-project",
|
||||
organization: "your-sentry-organization",
|
||||
},
|
||||
],
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
Then provide an auth token through environment variables (locally in `.env.local` file in `apps/mobile` directory) and your build environment:
|
||||
|
||||
```dotenv title="apps/mobile/.env.local"
|
||||
SENTRY_AUTH_TOKEN="your-sentry-auth-token"
|
||||
```
|
||||
|
||||
### Add the Sentry Metro plugin
|
||||
|
||||
To ensure unique Debug IDs are assigned to the generated bundles and source maps, add the Sentry Metro Plugin to the configuration.
|
||||
|
||||
Update `metro.config.js` to use `getSentryExpoConfig`:
|
||||
|
||||
```js title="metro.config.js"
|
||||
const { getSentryExpoConfig } = require("@sentry/react-native/metro");
|
||||
|
||||
const config = getSentryExpoConfig(__dirname);
|
||||
|
||||
module.exports = config;
|
||||
```
|
||||
|
||||
With the Expo plugin + Metro plugin in place, source maps are uploaded automatically during release native builds and EAS builds (debug builds typically rely on Metro's symbolication).
|
||||
|
||||
Take a moment to test your setup by triggering an error in your app, then confirm that source maps are resolving stack traces accurately in your [Sentry dashboard](https://sentry.io/settings/account/projects/). For advanced setup details, troubleshooting, or further customization with React Native and Expo, refer to the [official Sentry documentation](https://docs.sentry.io/platforms/react-native/guides/expo/sourcemaps/).
|
||||
|
||||
<Cards>
|
||||
<Card title="What are source maps?" href="https://web.dev/articles/source-maps" description="web.dev" />
|
||||
|
||||
<Card title="Uploading source maps" href="https://docs.sentry.io/platforms/react-native/sourcemaps/uploading/expo/" description="docs.sentry.io" />
|
||||
</Cards>
|
||||
Reference in New Issue
Block a user