npm package: @shaykec/appxray-web
Description: appxray SDK for React/Next.js/Vue web applications — gives AI agents inside-out access to your app
Latest version: 0.1.5

# @shaykec/appxray-web

appxray SDK for React, Next.js, and Vue web applications — gives AI coding agents inside-out access to your running app.

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

## 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 web 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-web`
> 3. If using Vite: add `appxrayVite()` to the plugins array in `vite.config.ts` (import from `@shaykec/appxray-web/vite`)
> 4. If not using Vite: add `import "@shaykec/appxray-web/auto"` to the app's entry file
> 5. If using Zustand: wrap each store with `appxrayMiddleware("storeName")` (import from `@shaykec/appxray-web/middleware/zustand`)
> 6. Verify the build succeeds and the app is discoverable

## What It Does

Embed this lightweight SDK in your web 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)
- Intercept network requests and responses
- Read/write localStorage and sessionStorage
- Navigate programmatically
- Interact with the UI — tap, type, swipe, fill forms
- Install API mocks without touching code
- Trace function calls and renders

## Install

```bash
npm install @shaykec/appxray-web
```

## Quick Start (Vite)

One line in your Vite config — no other code changes needed:

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import appxrayVite from "@shaykec/appxray-web/vite";

export default defineConfig({
  plugins: [react(), appxrayVite()],
});
```

Start your app, and it's immediately discoverable by the MCP server.

## Zustand Integration

Wrap your stores to expose state to the agent:

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

export const useTaskStore = create<TaskState>()(
  appxrayMiddleware("tasks")(
    (set) => ({
      tasks: [],
      addTask: (title) => set((s) => ({ tasks: [...s.tasks, { title }] })),
    })
  )
);
```

## Exports

| Import Path | Description |
|-------------|-------------|
| `@shaykec/appxray-web` | Core SDK |
| `@shaykec/appxray-web/vite` | Vite plugin (auto-injects SDK) |
| `@shaykec/appxray-web/react` | React hooks and components |
| `@shaykec/appxray-web/auto` | Auto-initialization |
| `@shaykec/appxray-web/middleware/zustand` | Zustand store middleware |
| `@shaykec/appxray-web/middleware/redux` | Redux middleware |

## 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-node`](https://www.npmjs.com/package/@shaykec/appxray-node) — Node.js backend SDK
- [`@shaykec/appxray-react-native`](https://www.npmjs.com/package/@shaykec/appxray-react-native) — React Native SDK

## License

MIT