npm package: @shaykec/appxray-react-native
Description: appxray SDK for React Native apps — gives AI agents inside-out access to your mobile app
Latest version: 0.1.5

# @shaykec/appxray-react-native

appxray SDK for React Native apps — gives AI coding agents inside-out access to your iOS and Android mobile app.

[![npm](https://img.shields.io/npm/v/@shaykec/appxray-react-native)](https://www.npmjs.com/package/@shaykec/appxray-react-native)

## Instant Setup — Paste This to Your AI Agent

Copy this into **Cursor**, **Claude Code**, or any MCP-capable AI agent chat and it will do the rest:

> Integrate appxray into my React Native app:
> 1. Add to MCP config (`.cursor/mcp.json`): `{ "mcpServers": { "appxray": { "command": "npx", "args": ["-y", "@shaykec/appxray-mcp-server"], "env": { "APPXRAY_AUTO_CONNECT": "true" } } } }`
> 2. Run `npm install @shaykec/appxray-react-native`
> 3. Create `src/appxray-setup.ts` that calls `appxray.init({ appName: "MyApp" })` and exports init/shutdown functions
> 4. In `App.tsx`, call `initAppXray()` inside a `useEffect` with `shutdownAppXray()` as cleanup
> 5. Optional: wrap Zustand stores with `appxrayMiddleware("storeName")` (import from `@shaykec/appxray-react-native/middleware/zustand`)
> 6. Verify the build succeeds and the app is discoverable

## What It Does

Embed this lightweight SDK in your React Native app, and AI agents (via the [appxray MCP server](https://www.npmjs.com/package/@shaykec/appxray-mcp-server)) can:

- Inspect the component tree with props and state
- Read and write state stores (Zustand, Redux)
- Monitor network requests and responses
- Read/write AsyncStorage
- Navigate programmatically
- Interact with the UI — tap, type, swipe, fill forms
- Install API mocks without touching code
- Trace function calls with an automatic Babel transformer

## Install

```bash
npm install @shaykec/appxray-react-native
```

## Quick Start

```typescript
// src/appxray-setup.ts
import appxray from "@shaykec/appxray-react-native";

export function initAppXray() {
  appxray.init({ appName: "MyApp" });
}
export function shutdownAppXray() {
  appxray.shutdown();
}
```

```typescript
// App.tsx
import { useEffect } from "react";
import { initAppXray, shutdownAppXray } from "./appxray-setup";

export default function App() {
  useEffect(() => {
    initAppXray();
    return () => shutdownAppXray();
  }, []);

  return <MainNavigator />;
}
```

## Zustand Integration

```typescript
import { create } from "zustand";
import { appxrayMiddleware } from "@shaykec/appxray-react-native/middleware/zustand";

export const useStore = create<AppState>()(
  appxrayMiddleware("app")(
    (set) => ({ /* your store */ })
  )
);
```

## Function Tracing

Add the Babel transformer for automatic function-level tracing:

```javascript
// babel.config.js
module.exports = {
  presets: ["module:@react-native/babel-preset"],
  plugins: [
    ["@shaykec/appxray-react-native/trace-transformer", { include: ["src/**"] }],
  ],
};
```

## Exports

| Import Path | Description |
|-------------|-------------|
| `@shaykec/appxray-react-native` | Core SDK and init |
| `@shaykec/appxray-react-native/provider` | React context provider |
| `@shaykec/appxray-react-native/middleware/zustand` | Zustand middleware |
| `@shaykec/appxray-react-native/trace-runtime` | Trace runtime helpers |
| `@shaykec/appxray-react-native/trace-transformer` | Babel transformer |

## MCP Server Required

This SDK exposes your app's internals via WebSocket. To connect an AI agent, add the [MCP server](https://www.npmjs.com/package/@shaykec/appxray-mcp-server) to your agent's config:

```json
{
  "mcpServers": {
    "appxray": {
      "command": "npx",
      "args": ["-y", "@shaykec/appxray-mcp-server"],
      "env": { "APPXRAY_AUTO_CONNECT": "true" }
    }
  }
}
```

## Related Packages

- [`@shaykec/appxray-mcp-server`](https://www.npmjs.com/package/@shaykec/appxray-mcp-server) — MCP server (required for AI agent access)
- [`@shaykec/appxray-web`](https://www.npmjs.com/package/@shaykec/appxray-web) — Web frontend SDK
- [`@shaykec/appxray-node`](https://www.npmjs.com/package/@shaykec/appxray-node) — Node.js backend SDK

## License

MIT