rn-backstage 1.4.4 → 1.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-backstage",
-  "version": "1.4.4",
+  "version": "1.4.5",
   "description": "A zero-dependency developer/QA debug panel for React Native apps",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -89,5 +89,7 @@
         }
       ]
     ]
-  }
+  },
+  "readme": "# rn-backstage\n\n[![npm version](https://img.shields.io/npm/v/rn-backstage.svg)](https://www.npmjs.com/package/rn-backstage)\n[![npm downloads](https://img.shields.io/npm/dm/rn-backstage.svg)](https://www.npmjs.com/package/rn-backstage)\n\nA zero-dependency developer/QA debug panel for React Native apps. Inspect device info, view state trees, monitor console logs, inspect network requests, and trigger custom actions — all from a sleek in-app panel.\n\n## Features\n\n- 🎯 **Draggable floating pill** — always accessible, repositionable trigger with safe area bounds\n- 📱 **Device & build info** — OS version, app version, build number, and custom data\n- 🌳 **State tree inspector** — visualize Redux, Zustand, or any store state\n- 📋 **Console log viewer** — intercepts all console methods with search & filtering\n- 🌐 **Network inspector** — intercepts fetch & XMLHttpRequest with request/response details, headers, body, timing, and copy-as-cURL\n- 🎚 **Feature flag toggle** — render switches to toggle flags in real-time without restarting\n- 🗄 **Storage viewer** — inspect, edit, and delete AsyncStorage/MMKV entries via a pluggable adapter\n- ⚡ **Quick actions** — add custom buttons (logout, clear cache, etc.)\n- 🔌 **Extensible tabs** — add custom tabs for app-specific debugging tools\n- 🎨 **Light & dark theme** — auto-follows device setting, or override manually\n- 📦 **Zero dependencies** — only peer deps are `react` and `react-native`\n\n## Installation\n\n```sh\nnpm install rn-backstage\n# or\nyarn add rn-backstage\n```\n\nNo additional native dependencies required!\n\n## Usage\n\n```tsx\nimport { Backstage } from 'rn-backstage'\n\nexport default function App() {\n  return (\n    <>\n      {/* Your app content */}\n      <Backstage\n        appVersion=\"1.2.3\"\n        buildNumber=\"42\"\n        bundleId=\"com.example.app\"\n        state={store.getState()}\n        quickActions={[\n          { title: 'Logout', onPress: handleLogout, destructive: true },\n          { title: 'Clear Cache', onPress: clearCache },\n        ]}\n        onCopyLogs={logs => Clipboard.setString(logs)}\n      />\n    </>\n  )\n}\n```\n\n## Network Inspector\n\nThe Network tab automatically intercepts all `fetch()` and `XMLHttpRequest` traffic — including libraries built on top of them like **Axios**, **Apisauce**, **ky**, and **Apollo Client**.\n\nEach request shows:\n\n- Method, URL, status code, and duration\n- Request & response headers\n- Request & response body (auto-parsed JSON with tree view)\n- Response size\n- Copy as cURL (long-press any request)\n\n```tsx\n<Backstage\n  // Network inspector is enabled by default\n  enableNetworkInspector={true}\n  // Exclude noisy URLs (analytics, Sentry, etc.)\n  networkFilters={['sentry.io', 'analytics', 'hot-update']}\n  // Limit body capture size (default: 64KB)\n  maxNetworkBodySize={65536}\n  // Auto-filters console.logs from Axios interceptors / fetch .then() chains\n  // out of the Logs tab (they're already in the Network tab). Default: true\n  autoFilterNetworkLogs={true}\n/>\n```\n\n## Feature Flag Toggle\n\nPass feature flags to render a dedicated **Flags** tab with toggle switches. The tab only appears when at least one flag is provided. Toggling calls your callback in real-time — no app restart needed.\n\n```tsx\nconst [flags, setFlags] = useState([\n  { key: 'dark_mode', label: 'Dark Mode', value: true, description: 'Enable dark theme' },\n  { key: 'beta', label: 'Beta Features', value: false, description: 'Experimental features' },\n])\n\n<Backstage\n  featureFlags={flags}\n  onToggleFeatureFlag={(key, value) => {\n    setFlags(prev => prev.map(f => (f.key === key ? { ...f, value } : f)))\n  }}\n/>\n```\n\n## Storage Viewer\n\nPass a `storageAdapter` to render a **Storage** tab that lets you browse, edit, add, and delete key-value entries. The tab only appears when an adapter is provided. Works with any storage backend — zero dependencies.\n\n```tsx\nimport AsyncStorage from '@react-native-async-storage/async-storage'\n;<Backstage\n  storageAdapter={{\n    getAllKeys: () => AsyncStorage.getAllKeys(),\n    getItem: key => AsyncStorage.getItem(key),\n    setItem: (key, value) => AsyncStorage.setItem(key, value),\n    removeItem: key => AsyncStorage.removeItem(key),\n  }}\n/>\n```\n\nMMKV example:\n\n```tsx\nimport { storage } from './mmkv'\n;<Backstage\n  storageAdapter={{\n    getAllKeys: () => Promise.resolve(storage.getAllKeys()),\n    getItem: key => Promise.resolve(storage.getString(key) ?? null),\n    setItem: (key, value) => Promise.resolve(storage.set(key, value)),\n    removeItem: key => Promise.resolve(storage.delete(key)),\n  }}\n/>\n```\n\n## Bug Report\n\nAdd a `bugReport` config to enable one-tap bug reporting. Tapping the 🐛 button in the panel header opens a composer that auto-attaches device info, logs, network activity, and state. Reports can be shared via the system share sheet or submitted to a webhook.\n\n```tsx\n<Backstage\n  bugReport={{\n    onSubmit: report => {\n      // Full BugReport object with all context\n      console.log(report.title, report.severity, report.logs.length)\n    },\n    // Optional: POST to a webhook\n    webhookUrl: 'https://your-api.com/bugs',\n    // Optional: capture screenshot (requires a library like react-native-view-shot)\n    captureScreenshot: () => viewShotRef.current.capture(),\n    maxLogsInReport: 50,\n    maxNetworkEntriesInReport: 20,\n  }}\n/>\n```\n\n## Props\n\n| Prop                     | Type                          | Default     | Description                                     |\n| ------------------------ | ----------------------------- | ----------- | ----------------------------------------------- |\n| `visible`                | `boolean`                     | `true`      | Show/hide the floating pill                     |\n| `theme`                  | `'light' \\| 'dark' \\| 'auto'` | `'auto'`    | Theme preference; auto follows device setting   |\n| `appVersion`             | `string`                      | `undefined` | App version to display                          |\n| `buildNumber`            | `string`                      | `undefined` | Build number                                    |\n| `bundleId`               | `string`                      | `undefined` | Bundle identifier                               |\n| `deviceInfo`             | `AppInfoItem[]`               | `[]`        | Additional device/app info rows                 |\n| `state`                  | `object`                      | `undefined` | State tree to inspect                           |\n| `quickActions`           | `QuickAction[]`               | `[]`        | Custom action buttons                           |\n| `featureFlags`           | `FeatureFlag[]`               | `[]`        | Feature flags with toggle switches              |\n| `onToggleFeatureFlag`    | `(key, val: boolean) => void` | `undefined` | Callback when a flag is toggled                 |\n| `storageAdapter`         | `StorageAdapter`              | `undefined` | Storage adapter for the Storage Viewer tab      |\n| `maxLogs`                | `number`                      | `500`       | Maximum logs to retain                          |\n| `logFilters`             | `string[]`                    | `[]`        | Messages to exclude from logs                   |\n| `onCopyLogs`             | `(logs: string) => void`      | `undefined` | Callback when copying logs                      |\n| `enableNetworkInspector` | `boolean`                     | `true`      | Enable/disable network request interception     |\n| `maxNetworkEntries`      | `number`                      | `500`       | Maximum network entries to retain               |\n| `maxNetworkBodySize`     | `number`                      | `65536`     | Max body size (bytes) to capture per request    |\n| `networkFilters`         | `string[]`                    | `[]`        | URL substrings to exclude from capture          |\n| `autoFilterNetworkLogs`  | `boolean`                     | `true`      | Auto-filter network callback logs from Logs tab |\n| `jsonMaxDepth`           | `number`                      | `10`        | Max nesting depth for all JSON tree views       |\n| `initialX`               | `number`                      | `undefined` | Initial X position for the floating pill        |\n| `initialY`               | `number`                      | `undefined` | Initial Y position for the floating pill        |\n| `pillText`               | `string`                      | `undefined` | Text on the pill (defaults to version or \"DEV\") |\n| `pillWidth`              | `number`                      | `60`        | Width of the floating pill                      |\n| `pillHeight`             | `number`                      | `32`        | Height of the floating pill                     |\n| `extraTabs`              | `BackstageTab[]`              | `[]`        | Additional custom tabs                          |\n| `bugReport`              | `BugReportConfig`             | `undefined` | Bug report config (shows 🐛 button in header)   |\n| `styles`                 | `BackstageStyleOverrides`     | `undefined` | Custom style overrides                          |\n| `children`               | `ReactNode`                   | `undefined` | Extra content in InfoTab                        |\n\n## Ref Methods\n\n```tsx\nconst ref = useRef<BackstageRef>(null)\n\nref.current?.open() // Open the panel\nref.current?.close() // Close the panel\nref.current?.clearLogs() // Clear all captured logs\nref.current?.submitBugReport() // Open bug report composer\n```\n\n## Individual Components\n\nAll internal components are exported for advanced use cases — compose your own custom debug UI:\n\n```tsx\nimport {\n  BackstagePanel,\n  FloatingPill,\n  TabBar,\n  InfoTab,\n  LogsTab,\n  LogItem,\n  NetworkTab,\n  NetworkItem,\n  FlagsTab,\n  StorageTab,\n  BugReportComposer,\n  JsonTreeView, // useful standalone for any JSON data\n} from 'rn-backstage'\n```\n\n## TestIDs\n\nAll interactive elements have consistent `testID` attributes for E2E testing. Import the `TestIDs` object to reference them:\n\n```tsx\nimport { TestIDs } from 'rn-backstage'\n\n// Static IDs\nTestIDs.floatingPill // 'backstage.floating-pill'\nTestIDs.panel // 'backstage.panel'\nTestIDs.header.closeButton // 'backstage.header.close'\n\n// Dynamic IDs (for items in lists)\nTestIDs.logItem.container(id) // 'backstage.log-item.{id}'\nTestIDs.flagsTab.flagSwitch(key) // 'backstage.flag.{key}'\nTestIDs.storageTab.entryRow(key) // 'backstage.storage.entry.{key}'\n```\n\n## License\n\nMIT\n",
+  "readmeFilename": "README.md"
 }