Install React Native DevTools — @buoy-gg/core setup guide

Q: Which React Buoy package do I install first?

@buoy-gg/core — it renders the floating menu. Every tool is a separate package (@buoy-gg/network, @buoy-gg/storage, and so on) that registers itself in the menu once installed, so you only ship the tools you actually use.

This is the reference for installing Buoy: packages, signing in, Desktop and MCP, and fixes for common problems. New to Buoy? Quick Start walks you through a first install and ends with a captured request.

Requirements

React Native0.70+

React18+

Core and Network are JavaScript only and run in Expo Go. A few tools ship native code and need a development build, such as Bench's native CPU and memory metrics. Each tool's page says what it needs.

Install with your agent

Paste the prompt into Claude Code, Cursor or Codex. The agent reads your package.json, installs the tools that match your app and mounts the menu. Review its changes before you commit them.

Let your coding agent install itClaude Code · Cursor · Codex

Read the prompt before you paste it

Install Buoy, the in-app devtools for React Native and Expo, in this project. Read the full instructions first: curl -fsSL https://buoy.gg/install.md Read the raw text, not a summary. If curl is unavailable, use any HTTP tool you have. Ask me to paste the document only if nothing can fetch it. Do the install yourself: inspect the repo, run the commands, edit the files. Do not hand me steps you can run. Work out the routine decisions from the repo: package manager, which app to target, where the menu mounts, which Buoy tools match the dependencies already installed. If Buoy is already partly installed, repair and extend it; never add a second mount, provider, or package set. When instructions conflict, follow this order: what I say here, then the document's rules about which packages exist and what needs my permission, then this project's own constraints, then the rest of the document, then your judgment. Ask me before: adding a native dependency, opening a browser or creating an account, changing what a production build does beyond what the document specifies, or anything hard to undo. Do not commit. You are not done when the packages install. Run this project's existing typecheck; add no tooling. Then report what you installed and why, what you skipped and why, every file you changed, what you verified, and the exact steps I take on the device to confirm the menu appears and captures a request.

The prompt asks your agent to inspect the project, choose matching tools and guide setup. Review its edits and verify the connection on your device.Read the setup instructions

Install by hand

Install the core menu and your first tool:

npm install @buoy-gg/core @buoy-gg/network

To install several tools at once, pick them here and copy the command:

Select your tools29 packages

Corerequired

npm install @buoy-gg/core @buoy-gg/network @buoy-gg/storage @buoy-gg/env @buoy-gg/react-query @buoy-gg/route-events @buoy-gg/highlight-updates @buoy-gg/perf-monitor @buoy-gg/js-top @buoy-gg/redux @buoy-gg/zustand @buoy-gg/jotai @buoy-gg/events @buoy-gg/console @buoy-gg/sentry @buoy-gg/images @buoy-gg/three @buoy-gg/assets @buoy-gg/tv-remote @buoy-gg/focus-inspector @buoy-gg/time-machine @buoy-gg/clock @buoy-gg/lifecycle @buoy-gg/location @buoy-gg/permissions @buoy-gg/impersonate @buoy-gg/scenarios @buoy-gg/ask-buoy @buoy-gg/image-overlay

Available Packages

Each package adds one tool to the floating menu. Install only the ones you need.

Package manager:

Camera

Supply camera feeds to supported iOS Simulator apps. Desktop account required; screen capture and non-QR generation need Pro.

Nothing to install — ships with Buoy Desktop

Sim Farm

Buoy Optimize on many iOS sims or Android phones at once. Each speed idea gets its own slim sim that acts like a real phone. Free with an account.

Nothing to install — ships with Buoy MCP

Chrome Farm

Many slim Chromes on one computer. Each runs your web app like a lone Chrome, so your tests and AI agent can drive them all at once. Free with an account.

Nothing to install — ships with Buoy MCP

Buoy Web

Let your AI use the web in Chrome with real clicks. Use Ask Buoy in Chrome's side panel, or let Claude Code, Cursor or Codex use Buoy's own tabs. The coding-tool part is free.

Nothing to install — ships with Buoy MCP

Core

Required

Account setup and floating menu for React Native tools. Camera runs separately in Desktop.

npm install @buoy-gg/core

Network

Inspect captured requests and responses. Preview Offline and latency conditions in React Native development builds.

npm install @buoy-gg/network

Storage

Inspect configured AsyncStorage, MMKV and SecureStore adapters; editing depends on access.

npm install @buoy-gg/storage

Environment

Inspect and validate the environment values you explicitly supply.

npm install @buoy-gg/env

React Query

TanStack Query devtools with cache inspection.

npm install @buoy-gg/react-query

Route Events

Track navigation changes and browse routes.

npm install @buoy-gg/route-events

Highlight Updates

Inspect observed component updates and available render-cause details in supported development builds.

npm install @buoy-gg/highlight-updates

Bench

Record available performance metrics and compare runs under consistent test conditions.

npm install @buoy-gg/perf-monitor

JS Top

Inspect captured JavaScript callback activity and available timing attribution.

npm install @buoy-gg/js-top

Redux DevTools

Inspect a connected Redux store, captured actions and supported restore controls.

npm install @buoy-gg/redux

Zustand DevTools

Inspect registered Zustand stores, captured changes and retained snapshots.

npm install @buoy-gg/zustand

Jotai DevTools

Inspect tracked Jotai atoms and retained changes from the connected store.

npm install @buoy-gg/jotai

Events Timeline

Review captured events from configured tools and export selected data.

npm install @buoy-gg/events

Console

Inspect supported JavaScript logs captured after setup, within retention limits.

npm install @buoy-gg/console

Sentry

See what your app sends to Sentry, and what it costs.

npm install @buoy-gg/sentry

Images

Inspect supported image loads, available cache signals, estimated memory and captured failures.

npm install @buoy-gg/images

Scene (Beta)

See the scene tree. Pick and edit 3D objects.

npm install @buoy-gg/three

Assets

Inspect registered assets, available sizes, duplicates and assets not loaded during the session.

npm install @buoy-gg/assets

TV Remote

Record supported TV input and replay through available host controls. Physical Apple TV is record-only.

npm install @buoy-gg/tv-remote

Focus Inspector

Inspect observed TV focus transitions and possible navigation problems; findings need review.

npm install @buoy-gg/focus-inspector

Time Machine

Capture and restore supported state through configured adapters; review skipped or failed items.

npm install @buoy-gg/time-machine

Clock

Move the app's clock to any date, freeze it or speed it up to test expiry, countdowns and renewals, and make the app refresh its sign-in token.

npm install @buoy-gg/clock

Lifecycle

Send the app to the background, interrupt it like a call, send a memory warning or a deep link, or relaunch it, then see what your code did.

npm install @buoy-gg/lifecycle

Location

Pin the app to any place, move it along a route, cross geofences, and test no GPS signal or location services off.

npm install @buoy-gg/location

Permissions

Make the app see not asked, allowed, limited, denied or blocked for location, camera, notifications and more, and test the prompt, the refusal and the trip to Settings.

npm install @buoy-gg/permissions

Impersonate

Use your configured, backend-authorized impersonation flow to test permitted identities.

npm install @buoy-gg/impersonate

Scenarios

Saved, parameterized one-tap app states for QA, support and demos.

npm install @buoy-gg/scenarios

Ask Buoy

Beta

Use a configured model endpoint to inspect supported tools and request actions under your policy.

npm install @buoy-gg/ask-buoy

Image Overlay

Overlay design mockups on your app for pixel-perfect comparison.

npm install @buoy-gg/image-overlay

Buoy needs a Free or Pro account. The plans have different history limits and features, and production access and Ask Buoy require Pro. Free has the basic MCP and Buoy Optimize. Pro adds the full MCP. See pricing for details.

bash

npx --package=@buoy-gg/core buoy login

npx --package=@buoy-gg/core buoy login

This opens your browser and signs you in. Then it writes a dev token to an env file. It adds that file to .gitignore too, if it isn't there yet. On Expo the name is EXPO_PUBLIC_BUOY_KEY. On bare React Native it is BUOY_KEY. Keep the prefix: Expo only puts EXPO_PUBLIC_ names in your app.

A dev token works in dev builds and sims for 30 days. Then run buoy login again. On Expo it goes in .env.development.local. Expo reads that file for expo start only. Bare React Native gets .env.local. A dev token opens nothing in a TestFlight, QA or store build. For those, your testers sign in with a code. See Test builds.

On Expo, Buoy reads EXPO_PUBLIC_BUOY_KEY by itself in dev builds. You only mount the menu. Keep it inside the same providers as your screens.

tsx

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  return (
    <>
      <YourApp />
      <FloatingDevTools />
    </>
  );
}

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  return (
    <>
      <YourApp />
      <FloatingDevTools />
    </>
  );
}

Two cases pass the value in with Buoy.init. React Native CLI doesn't load env files into process.env. So read BUOY_KEY with your app's env loader. A key in an Expo TestFlight or store build needs it too. Buoy only finds a key by itself in dev builds.

tsx

import { Buoy } from "@buoy-gg/core";

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

import { Buoy } from "@buoy-gg/core";

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

A key you pass in always wins over the one Buoy finds.

Test builds

TestFlight, QA and store builds can't use a dev token. Your testers sign in with a code instead.

Add your app at buoy.gg/dashboard/sites. Type app: and then its bundle id, like app:com.acme.shop.
Pass signIn to FloatingDevTools:

tsx

<FloatingDevTools signIn />

<FloatingDevTools signIn />

A tester taps Sign in. Then they allow the code on buoy.gg, and Buoy opens. Only show FloatingDevTools to your own testers. Buoy in a test or store build needs Pro or Business. See Phones and test builds.

Keys still work

You don't have to sign in. Your account key from buoy.gg/dashboard/licenses works the same as before, and it always will. Put it in the same env var, or pass it in:

tsx

<FloatingDevTools licenseKey="YOUR_LICENSE_KEY" />

<FloatingDevTools licenseKey="YOUR_LICENSE_KEY" />

Passing it in is fine for a solo project. On a team, use the env var. A key in a shared repo is shared by everyone who clones it.

For CI and test runs, use a bot key. A team admin makes one on the Team page. See Keys for bots and CI.

Desktop & AI (optional)

The packages above power the in-app menu. Desktop is free with a Buoy account. Free has the basic MCP and Buoy Optimize. Pro adds the full MCP.

Buoy Desktop is a dashboard for macOS, Windows and Linux. Install the sync client in your app with npm install @buoy-gg/external-sync. It ships separately so apps that never use Desktop don't carry it. Then download Buoy Desktop and launch it. Your app finds it on its own, because the broker address comes from the Metro host. See Buoy Desktop.
AI / MCP Server lets Claude Code, Cursor or any MCP editor drive your app:

bash

npx -y @buoy-gg/mcp@latest init

npx -y @buoy-gg/mcp@latest init

See AI / MCP Server for the full setup.

TypeScript Support

All packages include TypeScript definitions. You don't need any @types packages.

Monorepos & Enterprise Setups

unstable_enablePackageExports: false works. Big monorepos often turn off Metro's package-exports resolution for older dependencies. Buoy's packages ship legacy resolution shims, so they resolve either way.
Physical devices find Desktop on their own. The broker address comes from the Metro host, so devices on the same Wi-Fi reach your machine. socketURL overrides it for tunnels or a broker on another machine.
Scoped registries. Every package lives under the @buoy-gg scope, so a proxy registry only needs a .npmrc scope rule (@buoy-gg:registry=…).
No on-device UI for end users. Pass headless to FloatingDevTools for builds where only the desktop dashboard should see the session. See FloatingDevTools.

Troubleshooting

The floating button doesn't appear

Check that FloatingDevTools renders, including any access condition you wrapped it in, and that you restarted the dev server after installing.

Restart Metro with --clear. Metro caches the "optional package missing" result from before you installed the package.

bash

npx expo start --clear

npx expo start --clear

Buoy asks for account setup

Buoy didn't get your dev token or key. Run npx --package=@buoy-gg/core buoy login in your app's folder. On Expo, check that the name starts with EXPO_PUBLIC_. Then restart with npx expo start --clear. On React Native CLI, check that your env loader passes BUOY_KEY to Buoy.init.

An Android device over USB can't reach Desktop

Forward the broker port:

bash

adb reverse tcp:42831 tcp:42831

adb reverse tcp:42831 tcp:42831

Network shows no requests

Make sure the action sent a new request and didn't read cached data. Network Monitor lists the supported capture paths.

Next Steps

Quick Start: a first install, start to finish
FloatingDevTools: configuration options
Buoy Desktop: the desktop dashboard
AI / MCP Server: drive your app from your AI editor
Custom Tools: build your own debugging tools

Installation

Camera

Sim Farm

Chrome Farm

Buoy Web

Core

Network

Storage

Environment

React Query

Route Events

Highlight Updates

Bench

JS Top

Redux DevTools

Zustand DevTools

Jotai DevTools

Events Timeline

Console

Sentry

Images

Scene (Beta)

Assets

TV Remote

Focus Inspector

Time Machine

Clock

Lifecycle

Location

Permissions

Impersonate

Scenarios

Ask Buoy

Image Overlay