Code Guidelines

Apply these guidelines to all new and modified code in packages/core. Existing code may not follow these conventions — do not refactor it unless asked.

This SDK spans four surfaces: TypeScript/JS (packages/core/src/js/), Android (Java/Kotlin, packages/core/android/), iOS (ObjC/Swift, packages/core/ios/), and the JS↔native bridge (RNSentry TurboModule / legacy NativeModule) that connects them. Read the AGENTS.md for the surface you're touching — root, packages/core/, packages/core/android/, packages/core/ios/ — before writing. The bridge is where most SDK-specific bugs live; the deep guidance for it is in packages/core/AGENTS.md.

For non-trivial work — a new feature or integration, a public barrel-file change, or a change that crosses the native bridge — load the design-first skill to shape the modules and seams before writing code. When writing or modifying tests, also load the test-guidelines skill.

SDK Development Rules

Integrations

SDK features are packaged as integration factory functions that return an Integration (from @sentry/core). See src/js/integrations/ for the canonical shape (e.g. nativelinkederrors.ts):

const INTEGRATION_NAME = 'MyFeature';

export const myFeatureIntegration = (options: Partial<MyOptions> = {}): Integration => {
  return {
    name: INTEGRATION_NAME,
    setupOnce: () => { /* one-time global side effects, if any */ },
    setup: (client: Client) => { /* per-client wiring */ },
    processEvent: (event, hint, client) => { /* enrich/drop */ return event; },
  };
};

• Check prerequisites and feature flags early — if the feature is disabled or the native module is missing, log via debug and return without wiring anything up.
• Name the integration with a module-level INTEGRATION_NAME constant; don't inline the string.
• Integrations should be order-independent. If yours must run before/after another, reconsider the design.
• Register default integrations in src/js/integrations/default.ts; keep an integration's options and defaults with the integration, not scattered across options.ts.
• Clean up anything global (listeners, timers) — an integration that arms a timer or subscribes to an emitter must have a path that tears it down.

Native Bridge (JS side)

Every call into native goes through the NATIVE wrapper (src/js/wrapper.ts) / RNSentry TurboModule. Rules:

• Guard on availability. If enableNative is false or the module isn't linked, degrade gracefully — return a safe fallback, never throw into user code.
• Never let a native rejection escape. Wrap bridge calls; log via debug and return a fallback. A thrown promise rejection from the bridge becomes an unhandled rejection in the host app.
• Everything crossing the bridge must be serializable — plain JSON (no functions, class instances, undefined holes, circular refs, or BigInt). Both the New Architecture (JSI/TurboModule codegen) and the legacy bridge serialize payloads; a non-serializable value is silently dropped or throws on the native side. Verify toJSON/normalization round-trips.
• Do not wrap RNSentry's own scope-sync methods (setTag, setContext, addBreadcrumb, setUser, captureEnvelope, …). Wrapping them recurses — see the RNSENTRY_SKIP / ignoreTurboModules notes in packages/core/AGENTS.md.
• In this hot path, logger from @sentry/core is the Logs API (emits log events), not the debug logger. Use debug for diagnostics — see the TurboModule section of packages/core/AGENTS.md.

Native Bridge (native side)

• Android (packages/core/android/): resolve/reject the Promise on every path; never leak it. Release JNI local refs; don't let a native exception cross back into the bridge uncaught. Old vs new arch code lives in src/oldarch/ and src/newarch/; shared code in src/main/.
• iOS (packages/core/ios/): prefix classes RNSentry; use nullability annotations; watch for retain cycles in blocks (capture weakSelf). Route hybrid-SDK access through RNSentryInternal (see packages/core/ios/AGENTS.md), not deprecated PrivateSentrySDKOnly.
• A native exception must never crash the host app — catch at the bridge boundary and reject/log instead.

Codegen (New Architecture)

The bridge spec is codegen'd. src/js/NativeRNSentry.ts is the TurboModule spec; RNSentryReplayMask*NativeComponent.ts are Fabric component specs.

• Codegen only supports a restricted type vocabulary — primitives, Object (untyped map), arrays, and nullable via ?. No unions of literals, no generics, no Record<K,V> with non-string keys. If a method's shape can't be expressed, pass an Object and validate/parse on the native side.
• Any change to a Native*.ts spec is a bridge ABI change: it must land in lockstep across the JS spec, ios/RNSentry.mm, and the Android RNSentryModuleImpl, and stay backward-compatible with older native binaries a user may have cached. Treat it like a public API change.

Usage tracking & SDK metadata

The event's SDK interface carries sdk.integrations, sdk.packages, and an optional sdk.features list; the spec says a feature should be reported through either an integration or the features list, not both. RN takes the integrations route: unlike sentry-dart (which populates sdk.features via an explicit addFeature / SentryFeatures API), RN's @sentry/core reports usage only through event.sdk.integrations and does not populate sdk.features. So usage is reported implicitly:

• An installed integration is auto-reported by its name — @sentry/core collects the names of installed integrations into event.sdk.integrations. So the practical rule is: give the integration a stable, correct INTEGRATION_NAME, and register it (a default in integrations/default.ts, or client.addIntegration(...)) — that registration is the usage signal. A feature that runs without a registered, named integration is invisible to usage tracking.
• SDK identity/packages come from src/js/version.ts (SDK_NAME, SDK_PACKAGE_NAME, SDK_VERSION) surfaced by integrations/sdkinfo.ts, which also appends the native SDK package — not the place to register feature usage.
• Do not confuse this with addFeatureFlag on the native module (wrapper.ts / NativeRNSentry.ts) — that is the user-facing feature-flags product, unrelated to SDK usage tracking.

When adding something you want measured, make sure it lands as a named, registered integration rather than a bare side effect.

Logging

• debug (from @sentry/core) is the internal diagnostic logger — use it for all SDK diagnostics. It is tree-shaken / gated so it stays quiet in production.
• logger (from @sentry/core) is the Logs API — it emits user-visible log events. Never use it for internal diagnostics, and never in a hot path (see bridge rules above).
• Log at the right level: debug for lifecycle/config, warn for recoverable/degraded paths (native module missing, option ignored), error for failures that affect SDK behavior.

Privacy (PII)

• Never collect PII without gating on options.sendDefaultPii. This covers IP inference, device identifiers, deep-link URLs, navigation params, request/response bodies, and user-supplied context.
• Flag any change that could place user data into breadcrumbs, event payloads, span attributes, or logs for review.
• Deliberate exceptions exist and must be documented where they live (e.g. TurboModule module/method names are app-defined identifiers sent regardless of sendDefaultPii — see packages/core/AGENTS.md "Privacy"). Don't add new always-on data collection without that justification.