@buildlens/react-native

Production-ready React Native SDK for BuildLens — crash capture, breadcrumbs, network monitoring, and offline ingestion.

Install

pnpm add @buildlens/react-native

Optional peer dependencies for production:

• @react-native-async-storage/async-storage — queue persistence
• @react-native-community/netinfo — connectivity-aware flushing
• react-native-keychain — secure API key storage

Quick start

import BuildLens from '@buildlens/react-native';

await BuildLens.init({
  apiKey: 'bl_live_xxx',
  appVersion: '1.2.0',
  buildNumber: '42',
  debug: __DEV__,
});

BuildLens.setUser({ id: 'tester-1', email: '[email protected]' });
BuildLens.log('Checkout opened', { screen: 'Cart' });

Public API

| Method | Purpose | |--------|---------| | BuildLens.init(config) | Initialize SDK and plugins | | BuildLens.captureException(error, context?) | Report handled/unhandled errors | | BuildLens.captureMessage(message, level?, context?) | Structured message events | | BuildLens.captureFeedback(payload) | Manual tester feedback | | BuildLens.setUser(user) | Attach tester identity | | BuildLens.log(message, metadata?, level?) | Breadcrumb + low-priority event | | BuildLens.startSession() / endSession() | Session timeline markers | | BuildLens.flush() | Force queue upload | | BuildLens.close() | Teardown plugins and flush |

Tree-shakable plugins

import BuildLens, { createNetworkPlugin } from '@buildlens/react-native';
import { createSessionPlugin } from '@buildlens/react-native/plugins/session';

await BuildLens.init({
  apiKey: '...',
  plugins: [createNetworkPlugin(), createSessionPlugin()],
});

React error boundary

import { BuildLensErrorBoundary } from '@buildlens/react-native';
// or: import { BuildLensErrorBoundary } from '@buildlens/react-native/react';

<BuildLensErrorBoundary fallback={<Text>Something went wrong</Text>}>
  <App />
</BuildLensErrorBoundary>

Architecture

BuildLens (facade)
  └── BuildLensClient (kernel)
        ├── OfflineQueue (persist, priority, retry)
        ├── FetchTransport (batch ingest)
        ├── BreadcrumbStore
        └── Plugins
              ├── crash-handler
              ├── network (fetch interception)
              ├── session timeline
              └── device-metadata

Events POST to POST /v1/ingest/batch with bearer API key auth.

Design principles

• Zero runtime dependencies in core — small bundle, tree-shakeable subpaths
• Never crash the host app — all public calls are wrapped in safe handlers
• Offline-first — queue persists, retries with exponential backoff
• Priority eviction — drops oldest low-priority events when queue is full
• Redaction by default — strips tokens, passwords, and sensitive URL params
• Plugin architecture — opt-in features via plugins[] config