Installation

Get Buoy running in your React Native app in minutes.

Requirements

Quick Start

Install the core package and any tools you need:

Select your tools(17 packages)

All/None

npmyarnpnpmbun

Corerequired

Network

Storage

EnvironmentReact Query

Route Events

Debug Borders

Highlight Updates

BenchJS TopRedux DevToolsZustand DevToolsJotai DevToolsEvents TimelineConsoleImpersonateImage Overlay

npm install @buoy-gg/core @buoy-gg/network @buoy-gg/storage @buoy-gg/env @buoy-gg/react-query @buoy-gg/route-events @buoy-gg/debug-borders @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/impersonate @buoy-gg/image-overlay

Copy

Available Packages

Each package adds a new tool to your floating menu. Install only what you need.

Package manager:

npmyarnpnpmbun

Core

Required

The floating menu component. Required for all tools.

npm install @buoy-gg/core

Network

Monitor API requests, responses, timing, and errors.

npm install @buoy-gg/network

Storage

Browse and edit AsyncStorage, MMKV & SecureStore in real-time.

npm install @buoy-gg/storage

Environment

View and validate environment variables with type checking.

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

Debug Borders

Overhaul In Progress

Tap any element to see testID and styles.

npm install @buoy-gg/debug-borders

Highlight Updates

See WHY components re-render with visual overlays.

npm install @buoy-gg/highlight-updates

Bench

Track FPS, CPU & memory live and benchmark variants to prove what's faster.

npm install @buoy-gg/perf-monitor

JS Top

Task Manager for the JS thread — a live ranked table of what's eating your JS FPS.

npm install @buoy-gg/js-top

Redux DevTools

Inspect Redux state, actions, and time-travel debugging.

npm install @buoy-gg/redux

Zustand DevTools

Monitor Zustand store state, diffs, and changes in real-time.

npm install @buoy-gg/zustand

Jotai DevTools

Inspect Jotai atom state, diffs, and live event history.

npm install @buoy-gg/jotai

Events Timeline

Unified timeline across all tools for debugging flows with LLM-ready export.

npm install @buoy-gg/events

Console

A Chrome-DevTools console for every log on the device.

npm install @buoy-gg/console

Impersonate

Switch users, roles, and feature flags without rebuilding.

npm install @buoy-gg/impersonate

Image Overlay

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

npm install @buoy-gg/image-overlay

Register Your License Key

A license key is required for all plans, including free. Pass it as a prop to FloatingDevTools:

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

export default function App() {
  return (
    <>
      <YourApp />
      <FloatingDevTools licenseKey="YOUR_LICENSE_KEY" />
    </>
  );
}

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

export default function App() {
  return (
    <>
      <YourApp />
      <FloatingDevTools licenseKey="YOUR_LICENSE_KEY" />
    </>
  );
}

Don't have a key yet? Grab one at buoy.gg/pricing.

Desktop & AI (optional)

The packages above power the in-app floating menu. Two more surfaces connect to the same app — both Buoy Pro:

• Buoy Desktop — a full dashboard for macOS, Windows & Linux. Download it and launch it — your app finds it automatically (the broker address is derived from Metro, so physical devices work zero-config too). See Buoy Desktop.
• AI / MCP Server — drive your app from Claude Code, Cursor, or any MCP editor:

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 out of the box. No additional @types packages needed.

Monorepos & Enterprise Setups

Buoy is built to survive locked-down corporate React Native apps:

• After installing a new @buoy-gg package, restart Metro with --clear. Metro caches the "optional package missing" resolution — a plain reload never picks the new package up. This is the single most common "I installed it and nothing happened" cause.
• unstable_enablePackageExports: false works. Big monorepos often disable Metro's package-exports resolution for legacy dependencies; Buoy's packages ship legacy resolution shims so they resolve either way.
• Physical devices work zero-config. The desktop-sync broker address is derived from the Metro host, so devices on the same Wi-Fi find your machine automatically. Android over USB needs one command — adb reverse tcp:42831 tcp:42831 — and socketURL overrides everything for tunnels or a broker on another machine.
• Scoped registries — all packages live under the @buoy-gg scope, so a .npmrc scope rule (@buoy-gg:registry=…) is all a proxy registry needs.
• No on-device UI for end users — pass headless to FloatingDevTools for builds where only the desktop dashboard should see the session. See FloatingDevTools.

Next Steps

• Quick Start — Basic setup guide
• FloatingDevTools — Configuration options
• Buoy Desktop — The full desktop dashboard
• AI / MCP Server — Drive your app from your AI editor
• Custom Tools — Build your own debugging tools