React Buoy Devtools

Zero-config mobile dev tools that just work.

A single floating menu gives your entire team instant access to powerful debugging tools—in dev, staging, AND production. No configuration, no complexity. Just install packages and they automatically appear.

⚡ 2-Minute Setup

1. Install Core + Tools

npm install @react-buoy/core @react-buoy/env @react-buoy/network
# or: pnpm add / yarn add / bun add

2. Add to Your App

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

function App() {
  return (
    <>
      {/* Your app content */}
      <FloatingDevTools environment="local" userRole="admin" />
    </>
  );
}

3. That's It! 🎉

All installed tools automatically appear in your floating menu. No config needed.

💡 Pro Tip: Install all tools at once:
npm i @react-buoy/{core,env,network,storage,react-query,route-events,debug-borders}

🎯 What You Get

✨ Zero Configuration – Install packages, they auto-appear. No manual setup.

🏷️ Always-Visible Context – See your environment (dev/staging/prod) and role at a glance.

🔄 Persistent State – Tools remember their position and state through reloads.

👥 Team-Friendly – Same tools everywhere. Onboard new devs in minutes.

🎨 Beautiful UI – Draggable menu with modal and bottom-sheet views.

🔌 Fully Extensible – Drop in any React component as a custom tool.

📦 Available Tools

Install any combination to customize your dev menu:

Tool	Package	What It Does	Key Features
🌍 ENV	`@react-buoy/env`	Environment variable inspector	Validation, search, type checking, warnings
📡 Network	`@react-buoy/network`	API request monitor	Timeline view, filtering, performance metrics
💾 Storage	`@react-buoy/storage`	AsyncStorage/MMKV browser	View/edit/delete, bulk ops, validation
⚡ React Query	`@react-buoy/react-query`	TanStack Query devtools	Cache inspector, offline toggle, refetch
🧭 Routes	`@react-buoy/route-events`	Route & navigation tracker	Sitemap, stack view, event timeline
🎨 Borders	`@react-buoy/debug-borders`	Visual layout debugger	Colored component boundaries

Installation Pattern: All packages follow the same simple pattern:

npm install @react-buoy/{tool-name}
# Peer dependencies auto-detected (e.g., @tanstack/react-query, @react-native-async-storage/async-storage)

That's it! Once installed, each tool automatically appears in FloatingDevTools.

📸 View screenshots for each tool

Environment Inspector

Show preview

Network Monitor

Show preview

Storage Browser

Show preview

React Query DevTools

Show preview

Route Tracker

Show preview

Debug Borders

Show preview

🚀 Choose Your Path

👶 Just Starting?

Follow the 2-Minute Setup above
All tools work with zero config

🔧 Need Validation?

See Configuration below for env var and storage validation

🎨 Building Custom Tools?

Check out Custom Tools section

📖 Want Deep Dive?

View detailed package docs (collapsed sections)

⚙️ Configuration

Basic Usage (Zero Config)

<FloatingDevTools environment="local" userRole="admin" />

That's all you need! But if you want validation...

With Environment Variable Validation

import { FloatingDevTools } from "@react-buoy/core";
import type { EnvVarConfig } from "@react-buoy/core";

const requiredEnvVars: EnvVarConfig[] = [
  "API_URL", // Just check if exists
  { key: "DEBUG_MODE", expectedType: "boolean" },
  { key: "ENVIRONMENT", expectedValue: "development" },
];

<FloatingDevTools
  requiredEnvVars={requiredEnvVars}
  environment="local"
  userRole="admin"
/>;

With Storage Key Validation

import type { StorageKeyConfig } from "@react-buoy/core";

const requiredStorageKeys: StorageKeyConfig[] = [
  {
    key: "@app/session",
    expectedType: "string",
    description: "User session token",
    storageType: "async", // "async" | "mmkv" | "secure"
  },
];

<FloatingDevTools
  requiredStorageKeys={requiredStorageKeys}
  environment="local"
/>;

Complete Example with React Query

import React from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { FloatingDevTools } from "@react-buoy/core";
import type { EnvVarConfig, StorageKeyConfig } from "@react-buoy/core";

export default function App() {
  const queryClient = new QueryClient();

  const requiredEnvVars: EnvVarConfig[] = [
    "EXPO_PUBLIC_API_URL",
    { key: "EXPO_PUBLIC_DEBUG_MODE", expectedType: "boolean" },
  ];

  const requiredStorageKeys: StorageKeyConfig[] = [
    {
      key: "@app/session",
      expectedType: "string",
      storageType: "async",
    },
  ];

  return (
    <QueryClientProvider client={queryClient}>
      {/* Your app content */}

      <FloatingDevTools
        requiredEnvVars={requiredEnvVars}
        requiredStorageKeys={requiredStorageKeys}
        environment="local"
        userRole="admin"
      />
    </QueryClientProvider>
  );
}

💡 Note: All types (EnvVarConfig, StorageKeyConfig, etc.) are exported from @react-buoy/core

🔧 How It Works

React Buoy uses automatic package discovery. When you render <FloatingDevTools />, it:

Checks which @react-buoy/* packages are installed
Loads only the installed packages (lazy + safe)
Renders them automatically in the floating menu

No registration, no imports, no config arrays. Just install and go.

Behind the scenes: The core package attempts to require() each plugin. If installed, it loads. If not, it silently skips. This means:

✅ Zero config for the 90% use case
✅ No crashes from missing packages
✅ Automatic updates when you install new tools

Want full control? You can still manually configure tools with the apps prop (see Advanced Configuration).

🎨 Custom Tools

Any React component can be a dev tool! Perfect for:

🚀 Feature flag toggles
👤 User impersonation panels
✅ QA checklists
📊 Analytics dashboards
🗄️ Database browsers
📱 Push notification testers

Basic Custom Tool

import { FloatingDevTools } from "@react-buoy/core";
import type { InstalledApp } from "@react-buoy/core";

// Your custom tool - just a React component
function FeatureFlagsModal({ onClose }) {
  return (
    <View style={{ padding: 20 }}>
      <Text>Feature Flags</Text>
      {/* Your UI here */}
      <Button title="Close" onPress={onClose} />
    </View>
  );
}

// Define the tool
const customTools: InstalledApp[] = [
  {
    id: "feature-flags",
    name: "FLAGS",
    description: "Toggle feature flags",
    slot: "both", // "row" | "dial" | "both"
    icon: ({ size }) => <YourIcon size={size} />,
    component: FeatureFlagsModal,
    props: {},
  },
];

// Add to FloatingDevTools
<FloatingDevTools
  apps={customTools} // Your custom tools
  environment="local"
/>;

✨ Auto-discovery still works! Custom tools merge with auto-discovered tools. Same ID = your custom tool overrides.

📚 Package Details

🌍 Environment Inspector (@react-buoy/env)

What It Does

Visual health check for your app configuration. Validates environment variables, checks types, and warns about missing/incorrect values.

Install

npm install @react-buoy/env

Features

✅ Visual validation of required environment variables
🔍 Search and filter across all env vars
🎯 Type checking (string, number, boolean, object)
⚠️ Clear warnings for missing or incorrect values
📋 Copy values to clipboard

Optional: Helper Functions for Better DX

import { createEnvVarConfig, envVar } from "@react-buoy/env";
import type { EnvVarConfig } from "@react-buoy/core";

const requiredEnvVars: EnvVarConfig[] = createEnvVarConfig([
  envVar("API_URL").exists(),
  envVar("DEBUG_MODE").withType("boolean").build(),
  envVar("ENVIRONMENT").withValue("development").build(),
]);

📡 Network Inspector (@react-buoy/network)

What It Does

Real-time network request monitoring with timeline view, detailed inspection, and performance stats.

Install

npm install @react-buoy/network

Features

📊 Timeline view of all network requests
🔍 Detailed request/response inspection with JSON viewer
⚡ Performance metrics and timing breakdown
🎛️ Filter by status, method, URL patterns
📋 Copy request details (curl, JSON, etc.)
🔴 Highlight failed requests

💾 Storage Explorer (@react-buoy/storage)

What It Does

Real-time storage browser for AsyncStorage, MMKV, and SecureStore with live updates and bulk operations.

Install

npm install @react-buoy/storage
npm install @react-native-async-storage/async-storage  # peer dependency

Features

🗂️ Browse all AsyncStorage, MMKV, and SecureStore data
✏️ Edit storage values in real-time
🗑️ Bulk delete operations
🔍 Search and filter storage keys
⚠️ Validation for required storage keys
📋 Copy keys/values

Supports Multiple Storage Types

AsyncStorage: React Native standard
MMKV: Encrypted, faster alternative
SecureStore: iOS Keychain / Android Keystore

⚡ React Query DevTools (@react-buoy/react-query)

What It Does

TanStack Query devtools adapted for mobile with query explorer, cache manipulation, and offline toggle.

Install

npm install @react-buoy/react-query
npm install @tanstack/react-query  # peer dependency (v5+)

Setup

Wrap your app with QueryClientProvider:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { FloatingDevTools } from "@react-buoy/core";

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Your app */}
      <FloatingDevTools environment="local" />
    </QueryClientProvider>
  );
}

Features

🔍 Query explorer with real-time data
🗂️ Cache inspection and manipulation
📊 Query performance metrics
🔄 Manual query refetching and invalidation
📶 WiFi Toggle - Simulate offline mode
🎨 Query state visualization (loading, error, success)

🧭 Route Events (@react-buoy/route-events)

What It Does

Comprehensive route tracking and visualization for Expo Router applications. Monitor route changes, explore your app's sitemap, and visualize the navigation stack.

Install

npm install @react-buoy/route-events
npm install expo-router @react-navigation/native  # peer dependencies

Features

🗺️ Route Sitemap - Browse all routes with search
📊 Event Timeline - Chronological route changes
🏗️ Navigation Stack - Real-time stack visualization
🔍 Event Inspection - Detailed params, segments, timing
🎯 Filtering - Filter by pathname patterns
⏱️ Performance Metrics - Navigation timing
✨ Zero Config - Auto-tracks when modal opens

Bonus: Custom Analytics Hook

import { useRouteObserver } from "@react-buoy/route-events";

export default function RootLayout() {
  useRouteObserver((event) => {
    analytics.trackPageView({
      path: event.pathname,
      params: event.params,
      timeSpent: event.timeSincePrevious,
    });
  });

  return <Stack />;
}

🎨 Debug Borders (@react-buoy/debug-borders)

What It Does

Visual debugging tool that adds colored borders around all React Native components to identify layout issues and component boundaries.

Install

npm install @react-buoy/debug-borders

Features

🎨 Colored borders around all components
🎯 Instant layout debugging
🔍 Component nesting visualization
🎭 Direct Toggle - Tap icon to enable/disable
💚 Visual Feedback - Icon changes color (gray → green)
⚡ Zero performance impact when disabled

Usage

Zero Config (Recommended): Just install and it auto-appears as a "BORDERS" button in the floating menu.

Standalone (without FloatingDevTools):

import { DebugBordersStandaloneOverlay } from "@react-buoy/debug-borders";

function App() {
  return (
    <>
      {/* Your app */}
      <DebugBordersStandaloneOverlay />
    </>
  );
}

🏗️ Advanced Configuration

📚 Expand for advanced topics

Manual Tool Configuration

Want to override auto-discovery with full control? Use factory functions:

import { FloatingDevTools } from "@react-buoy/core";
import { createEnvTool } from "@react-buoy/env";
import { createNetworkTool } from "@react-buoy/network";

const customTools = [
  createEnvTool({
    name: "ENVIRONMENT",  // Custom name
    iconColor: "#9333EA",  // Custom color
    requiredEnvVars: [...],
  }),
  createNetworkTool({
    name: "API MONITOR",
    iconColor: "#EC4899",
  }),
];

<FloatingDevTools
  apps={customTools}  // Overrides auto-discovery for these IDs
  environment="production"
/>

Complete Manual Setup (No Auto-Discovery)

import type { InstalledApp } from "@react-buoy/core";
import { EnvVarsModal } from "@react-buoy/env";
import { NetworkModal } from "@react-buoy/network";
import { EnvLaptopIcon, WifiCircuitIcon } from "@react-buoy/shared-ui";

const manualTools: InstalledApp[] = [
  {
    id: "env",
    name: "ENV",
    description: "Environment debugger",
    slot: "both",
    icon: ({ size }) => <EnvLaptopIcon size={size} colorPreset="green" noBackground />,
    component: EnvVarsModal,
    props: { requiredEnvVars: [...] },
  },
  {
    id: "network",
    name: "NET",
    description: "Network logger",
    slot: "both",
    icon: ({ size }) => <WifiCircuitIcon size={size} colorPreset="cyan" noBackground />,
    component: NetworkModal,
    props: {},
  },
];

<FloatingDevTools apps={manualTools} environment="local" />

Slot Types

Control where tools appear:

type AppSlot = "row" | "dial" | "both";

"row": Always-visible header (environment/role badges)
"dial": Floating expandable menu
"both": Available in both locations (default)

Launch Modes

type LaunchMode = "self-modal" | "host-modal" | "inline" | "toggle-only";

"self-modal": Tool manages its own modal (default for most)
"host-modal": Core manages the modal lifecycle
"inline": Renders inline (no modal)
"toggle-only": Just triggers an action (e.g., debug-borders)

🧩 Advanced Features

JSON Viewer & Diff Tools

All tools that display data (Network, Storage, React Query) use optimized JSON viewers:

Tree View

Like Redux DevTools - explore nested objects with expand/collapse

Side-by-Side Diff

Like VS Code - compare payloads visually

Type Filtering

Quickly find what you need in large payloads:

String values
Numbers
Booleans
Null/undefined
Objects
Arrays
Functions

Example: Debugging a 5MB API response → filter only booleans to check feature flags, or search undefined keys to spot missing data.

State Persistence

React Buoy remembers:

Which tools are open
Tool positions (if dragged)
User preferences

Storage Key: @apphost_open_apps

This means your debugging session survives:

✅ Hot reloads
✅ App restarts
✅ Crash recovery

Production Usage

React Buoy is production-safe with proper access controls:

import { FloatingDevTools } from "@react-buoy/core";
import { useUser } from "./auth";

function App() {
  const user = useUser();
  const showDevTools = user.role === "admin" || __DEV__;

  return (
    <>
      {/* Your app */}
      {showDevTools && (
        <FloatingDevTools
          environment={process.env.ENVIRONMENT}
          userRole={user.role}
        />
      )}
    </>
  );
}

Recommendation: Gate with your existing authentication/authorization system.

🆚 Why React Buoy?

vs. Reactotron

✅ Zero config (Reactotron requires manual command registration)
✅ In-app UI (Reactotron requires external app)
✅ Production-safe with auth (Reactotron is dev-only)
✅ Plugin architecture (install packages = auto-appear)

vs. Flipper

✅ Zero setup (Flipper requires native config + desktop app)
✅ Works on physical devices out-of-the-box
✅ Lightweight (Flipper is heavy)
✅ Team-friendly (no desktop app to install)

vs. react-native-debugger

✅ Modern (supports Hermes, new architecture)
✅ In-app (no external tools)
✅ Extensible (custom tools as React components)
✅ Production-ready

🤝 Real-World Use Case

Scenario: Debugging a payment flow issue in staging

Environment badge shows you're in staging (not prod!)
Role badge confirms you're logged in as "QA"
Tap Network to watch API calls in real-time
Open Storage to see what's persisted locally
Check React Query to inspect cached payment data
Use Routes to see the navigation flow
Launch your custom Payment Debug tool

All from one floating menu that follows you through every screen.

📝 License

🚀 Learn More

Resources:

Example App - Full working example with all packages
Package Source - Individual package source code
Changelog - Version history

Contributing:

Report bugs: GitHub Issues
Feature requests welcome!

💙 Credits

Big thanks to galaxies.dev — their content helped me get up to speed with React Native early on, and I strongly recommend it as a resource for anyone making the jump from web to mobile.

Name		Name	Last commit message	Last commit date
Latest commit History 194 Commits
.changeset		.changeset
.github		.github
docs		docs
example		example
packages		packages
patches		patches
plan		plan
scripts		scripts
tests/smoke		tests/smoke
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
lerna.json		lerna.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
test-exports.mjs		test-exports.mjs
tsconfig.json		tsconfig.json

License

LovesWorking/react-native-buoy

Folders and files

Latest commit

History

Repository files navigation

React Buoy Devtools

⚡ 2-Minute Setup

1. Install Core + Tools

2. Add to Your App

3. That's It! 🎉

🎯 What You Get

📦 Available Tools

Environment Inspector

Network Monitor

Storage Browser

React Query DevTools

Route Tracker

Debug Borders

🚀 Choose Your Path

⚙️ Configuration

Basic Usage (Zero Config)

With Environment Variable Validation

With Storage Key Validation

Complete Example with React Query

🔧 How It Works

🎨 Custom Tools

Basic Custom Tool

📚 Package Details

What It Does

Install

Features

Optional: Helper Functions for Better DX

What It Does

Install

Features

What It Does

Install

Features

Supports Multiple Storage Types

What It Does

Install

Setup

Features

What It Does

Install

Features

Bonus: Custom Analytics Hook

What It Does

Install

Features

Usage

🏗️ Advanced Configuration

Manual Tool Configuration

Complete Manual Setup (No Auto-Discovery)

Slot Types

Launch Modes

🧩 Advanced Features

Tree View

Side-by-Side Diff

Type Filtering

🆚 Why React Buoy?

vs. Reactotron

vs. Flipper

vs. react-native-debugger

🤝 Real-World Use Case

📝 License

🚀 Learn More

💙 Credits

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages