Ship React Native and Expo SDK support

.agents/skills/exceptionless-javascript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: exceptionless-javascript
-description: Use this skill when a developer wants to install, configure, troubleshoot, or integrate Exceptionless JavaScript clients for browser, Node.js, React, Vue, AngularJS, Express, Next.js, SvelteKit, or custom runtimes. Use it for API keys, startup, self-hosting, sending errors/logs/feature usage/404/custom events, indexed event properties, sessions, heartbeats, user identity, PII/data exclusions, plugins, runtime client configuration values, queues, and production setup even if they only ask "how do I wire up Exceptionless?"
+description: Use this skill when a developer wants to install, configure, troubleshoot, or integrate Exceptionless JavaScript clients for browser, Node.js, React, React Native, Expo, Vue, AngularJS, Express, Next.js, SvelteKit, or custom runtimes. Use it for API keys, startup, self-hosting, sending errors/logs/feature usage/404/custom events, indexed event properties, sessions, heartbeats, user identity, PII/data exclusions, plugins, runtime client configuration values, queues, native crash reporting, and production setup even if they only ask "how do I wire up Exceptionless?"
 ---
 
 # Exceptionless JavaScript SDK
@@ -38,6 +38,7 @@ Read only the reference that matches the user's runtime, then add shared referen
 - `@exceptionless/browser`: [references/client-browser.md](references/client-browser.md)
 - `@exceptionless/node`: [references/client-node.md](references/client-node.md)
 - `@exceptionless/react`: [references/client-react.md](references/client-react.md)
+- `@exceptionless/react-native`: [references/client-react-native.md](references/client-react-native.md)
 - `@exceptionless/vue`: [references/client-vue.md](references/client-vue.md)
 - `@exceptionless/angularjs`: [references/client-angularjs.md](references/client-angularjs.md)
 - Sending events: [references/sending-events.md](references/sending-events.md)
@@ -52,6 +53,8 @@ Read only the reference that matches the user's runtime, then add shared referen
 
 - Use `Exceptionless.startup(...)` once during app startup. `startup()` with no args is used later by lifecycle plugins to resume timers/queue processing.
 - Use the singleton from the platform package when automatic capture matters. Create `ExceptionlessClient` manually only for custom pipelines or tests.
+- For React Native or Expo apps, use `@exceptionless/react-native`; do not substitute `@exceptionless/browser` or `@exceptionless/react`.
+- In Expo, add `@exceptionless/react-native/expo-plugin` when native iOS crash reporting is expected. Expo Go can report JavaScript errors but cannot load the native crash reporter.
 - `submitException` and `createException` take an `Error`. For unknown caught values, use exported `toError(value)` when available.
 - `markAsCritical()` marks the event critical; `markAsCritical(false)` leaves tags unchanged.
 - `config.serverUrl` also sets `configServerUrl` and `heartbeatServerUrl`; assign custom endpoint overrides after setting `serverUrl`.
@@ -80,4 +83,7 @@ Verify behavior in:
 - `packages/core/src/submission/DefaultSubmissionClient.ts`
 - `packages/browser/src/BrowserExceptionlessClient.ts`
 - `packages/node/src/NodeExceptionlessClient.ts`
+- `packages/react-native/src/ReactNativeExceptionlessClient.ts`
+- `packages/react-native/src/plugins/ReactNativeErrorPlugin.ts`
+- `packages/react-native/src/plugins/NativeCrashPlugin.ts`
 - Package READMEs and `example/` apps.

.agents/skills/exceptionless-javascript/references/client-react-native.md

@@ -0,0 +1,124 @@
+# @exceptionless/react-native
+
+Use for React Native and Expo apps. This package adds a React Native client, AsyncStorage-backed persistence, React Native/Hermes stack parsing, lifecycle handling, global JavaScript error capture, an error boundary, and iOS native crash reporting.
+
+## Install
+
+Expo:
+
+```bash
+npx expo install @exceptionless/react-native @react-native-async-storage/async-storage
+```
+
+React Native CLI:
+
+```bash
+npm install @exceptionless/react-native @react-native-async-storage/async-storage
+cd ios && pod install
+```
+
+For Expo development or standalone builds, add the config plugin:
+
+```json
+{
+  "expo": {
+    "plugins": ["@exceptionless/react-native/expo-plugin"]
+  }
+}
+```
+
+Native iOS crash reporting requires an Expo development build, a standalone build, or a bare React Native app. Expo Go can capture JavaScript errors but cannot load the native crash reporter.
+
+## Configure
+
+Call `startup` once during app initialization:
+
+```tsx
+import { Exceptionless } from "@exceptionless/react-native";
+
+await Exceptionless.startup((config) => {
+  config.apiKey = "API_KEY_HERE";
+  config.setUserIdentity("12345678", "Blake");
+  config.defaultTags.push("React Native");
+});
+```
+
+For self-hosted Exceptionless:
+
+```tsx
+await Exceptionless.startup((config) => {
+  config.apiKey = "API_KEY_HERE";
+  config.serverUrl = "https://exceptionless.example.com";
+});
+```
+
+For local simulator development, prefer `http://localhost:<port>` when the app is running in the iOS simulator. Start Expo with `--localhost` or set `REACT_NATIVE_PACKAGER_HOSTNAME=localhost` so Metro bundle URLs in stack traces also use localhost. Use a LAN IP only when a physical device must reach a server on the development machine.
+
+## Error Boundary
+
+Wrap rendering surfaces to capture React render errors and attach the React component stack to `@error.data["@component_stack"]`:
+
+```tsx
+import { Text } from "react-native";
+import { ExceptionlessErrorBoundary } from "@exceptionless/react-native";
+
+export function App() {
+  return (
+    <ExceptionlessErrorBoundary fallback={<Text>Something went wrong.</Text>}>
+      <YourApp />
+    </ExceptionlessErrorBoundary>
+  );
+}
+```
+
+React error boundaries do not catch event handlers, async failures, or manually swallowed errors. Submit those explicitly.
+
+## Send
+
+```tsx
+import { Exceptionless, toError } from "@exceptionless/react-native";
+
+try {
+  await saveProfile();
+} catch (error) {
+  await Exceptionless.submitException(toError(error));
+}
+
+await Exceptionless.submitLog("mobile", "Profile opened", "info");
+await Exceptionless.submitFeatureUsage("Profile Editor");
+
+await Exceptionless.createException(new Error("Checkout failed"))
+  .addTags("checkout", "mobile")
+  .setProperty("orderId", "12345")
+  .markAsCritical(true)
+  .submit();
+```
+
+## Captured Behavior
+
+- Unhandled JavaScript errors and unhandled promise rejections are captured automatically after startup.
+- React Native/Hermes stack frames are parsed into structured Exceptionless stack frames.
+- iOS native crashes are persisted by PLCrashReporter and submitted on the next launch.
+- Device, OS, locale, React Native version, sessions, and lifecycle state are captured when available.
+- Event queue storage uses `@react-native-async-storage/async-storage`.
+
+## Troubleshooting
+
+- If native crashes do not appear in Expo, verify the app is not running in Expo Go and that the config plugin is present before rebuilding the native app.
+- If simulator submissions cannot reach a local Exceptionless server, use `http://localhost:<port>` for iOS Simulator and make sure Metro is not running in Expo's default LAN mode. Physical devices need a reachable LAN host.
+- For malformed or unexpected stacks, verify behavior in `ReactNativeErrorPlugin` tests before changing parser logic.
+- For native crash report loss concerns, verify `NativeCrashPlugin` only clears pending reports after at least one report is retrieved and submitted.
+
+## Source Anchors
+
+- `packages/react-native/README.md`
+- `packages/react-native/src/ReactNativeExceptionlessClient.ts`
+- `packages/react-native/src/ExceptionlessErrorBoundary.tsx`
+- `packages/react-native/src/plugins/ReactNativeErrorPlugin.ts`
+- `packages/react-native/src/plugins/ReactNativeGlobalHandlerPlugin.ts`
+- `packages/react-native/src/plugins/ReactNativeLifeCyclePlugin.ts`
+- `packages/react-native/src/plugins/NativeCrashPlugin.ts`
+- `packages/react-native/src/storage/AsyncStorageProvider.ts`
+- `packages/react-native/exceptionless-react-native.podspec`
+- `packages/react-native/expo-plugin/withExceptionless.cjs`
+- `example/expo/`

.prettierignore

@@ -3,6 +3,9 @@
 node_modules
 minver
 example/svelte-kit/.svelte-kit
+example/expo/.expo
+example/expo/android
+example/expo/ios
 
 # Ignore files for PNPM, NPM and YARN
 package-lock.json

.vscode/launch.json

@@ -1,6 +1,17 @@
 {
   "version": "0.2.0",
   "configurations": [
+    {
+      "name": "Expo iOS Example",
+      "request": "launch",
+      "type": "node",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "ios", "--workspace=example/expo"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "cwd": "${workspaceRoot}",
+      "skipFiles": ["<node_internals>/**"]
+    },
     {
       "name": "Express",
       "program": "${workspaceRoot}/example/express/app.js",

README.md

@@ -10,7 +10,7 @@ The definition of the word exceptionless is: to be without exception. Exceptionl
 
 You can install the npm package via `npm install @exceptionless/browser --save`
 or via cdn [`https://unpkg.com/@exceptionless/browser`](https://unpkg.com/@exceptionless/browser).
-Next, you just need to call startup during your apps startup to automatically
+Next, you just need to call startup during your app's startup to automatically
 capture unhandled errors.
 
 ```js
@@ -38,7 +38,7 @@ try {
 ## Node
 
 You can install the npm package via `npm install @exceptionless/node --save`.
-Next, you just need to call startup during your apps startup to automatically
+Next, you just need to call startup during your app's startup to automatically
 capture unhandled errors.
 
 ```js
@@ -63,6 +63,29 @@ try {
 }
 ```
 
+## React Native / Expo
+
+You can install the npm package via
+`npm install @exceptionless/react-native @react-native-async-storage/async-storage`.
+Next, you just need to call startup during your apps startup to automatically
+capture unhandled errors, promise rejections, and native iOS crashes.
+
+```tsx
+import { Exceptionless, toError } from "@exceptionless/react-native";
+
+await Exceptionless.startup((c) => {
+  c.apiKey = "API_KEY_HERE";
+  c.setUserIdentity("12345678", "Blake");
+  c.defaultTags.push("Example", "React Native");
+});
+
+try {
+  throw new Error("test");
+} catch (error) {
+  await Exceptionless.submitException(toError(error));
+}
+```
+
 ## Using Exceptionless
 
 ### Installation
@@ -223,7 +246,7 @@ instance. This is configured by setting the `serverUrl` on the default
 ```js
 await Exceptionless.startup((c) => {
   c.apiKey = "API_KEY_HERE";
-  c.serverUrl = "https://localhost:5100";
+  c.serverUrl = "https://ex.dev.localhost:7111";
 });
 ```
 

eslint.config.mjs

@@ -5,7 +5,7 @@ import vitest from "@vitest/eslint-plugin";
 import tseslint from "typescript-eslint";
 
 export default defineConfig(
-  { ignores: ["**/dist/", "**/node_modules/", ".agents/", "example/"] },
+  { ignores: ["**/dist/", "**/node_modules/", ".agents/", "example/", "**/expo-plugin/", "**/react-native.config.*"] },
   eslint.configs.recommended,
   {
     extends: tseslint.configs.recommendedTypeChecked,

example/browser/index.js

@@ -9,7 +9,7 @@ await Exceptionless.startup((c) => {
   c.services.log = new TextAreaLogger("logs", c.services.log);
 
   c.apiKey = "LhhP1C9gijpSKCslHHCvwdSIz298twx271nTest";
-  c.serverUrl = "https://localhost:5100";
+  c.serverUrl = "https://ex.dev.localhost:7111";
   c.updateSettingsWhenIdleInterval = 15000;
   c.usePersistedQueueStorage = true;
   c.setUserIdentity("12345678", "Blake");

example/expo/.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+.expo/
+dist/
+ios/
+android/
+*.xcworkspace
+Pods/
+
+# @generated expo-cli sync-2b81b286409207a5da26e14c78851eb30d8ccbdb
+# The following patterns were generated by expo-cli
+
+expo-env.d.ts
+# @end expo-cli