All but React Native are in beta.
All but React Native are in beta.


Buoy on your phone, in 2 minutesBeta. Use Buoy in your app on iOS and Android. This guide is for React apps built with Capacitor. Ionic React uses the same steps and web tools. We have tested Capacitor 7. Other versions need more tests.
Let your coding agent install Buoy in your app:
To set it up by hand, follow the steps below.
Keep React and React DOM in your app.
Add react-native-web 0.21 and the tools you want.
Keep all Buoy packages on the same release.
npm install @buoy-gg/core react-native-web @buoy-gg/network @buoy-gg/storage @buoy-gg/external-sync
npm install @buoy-gg/core react-native-web @buoy-gg/network @buoy-gg/storage @buoy-gg/external-sync
You do not need React Native or Expo. See web setup for state tools and routes.
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { buoy } from '@buoy-gg/core/vite';
export default defineConfig({
plugins: [react(), buoy()],
});
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { buoy } from '@buoy-gg/core/vite';
export default defineConfig({
plugins: [react(), buoy()],
});
The plugin finds each Buoy tool your app installed.
Buoy loads them for you. You add no imports.
Install a tool later and it shows up.
The dev server restarts when your tool list changes.
To leave a tool out, use buoy({ exclude: ['console'] }).
The plugin also adds Buoy's early hook to index.html.
The hook runs before your app code starts.
It sees calls and listeners from app boot.
It also helps track renders and early web calls.
Phone plugin capture runs in debug builds.
It sees calls that go to the phone's code.
Plugins made of JavaScript alone do not show there.
import { BuoyDevTools } from '@buoy-gg/core/web/auto';
// Inside your app's existing providers:
<IonApp>
<IonReactRouter>
<IonRouterOutlet>{/* your routes */}</IonRouterOutlet>
</IonReactRouter>
<BuoyDevTools signIn />
</IonApp>
import { BuoyDevTools } from '@buoy-gg/core/web/auto';
// Inside your app's existing providers:
<IonApp>
<IonReactRouter>
<IonRouterOutlet>{/* your routes */}</IonRouterOutlet>
</IonReactRouter>
<BuoyDevTools signIn />
</IonApp>
BuoyDevTools shows Buoy only in debug builds.
On a phone, it uses the app's debug flag.
In a browser, it uses your dev build.
Other builds don't load Buoy's tools or menu.
They still load the early hook.
It stays off unless Buoy ran in that app in the last week.
Set enabled to choose for yourself.
It takes the same props as FloatingDevTools.
Set the viewport so Buoy can avoid the notch:
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
In Ionic, put Buoy in IonApp. Keep it out of IonRouterOutlet.
This keeps page moves from moving Buoy too.
Plain React apps can mount beside their router.
A phone debug run may use a Vite production bundle.
So Buoy reads Capacitor.DEBUG from the phone app.
On iOS, CAPACITOR_DEBUG in Info.plist can turn it on.
Check that flag when you test a release build.
Android back closes the open Buoy tool first.
Ionic's own popups still close before Buoy tools.
Plain Capacitor needs @capacitor/app for the back hook.
If your app has its own back listener, check
isBuoyHoldingBackButton() from @buoy-gg/core/web.
Skip your back action while it returns true.
Put the early hook first in your entry file, before React DOM:
// src/main.tsx
import '@buoy-gg/core/web/register';
// src/main.tsx
import '@buoy-gg/core/web/register';
Then import each tool's /web entry and pass them as modules.
Use package names as keys. Notifications uses 'push-notifications'.
Keep modules outside your components.
import * as network from '@buoy-gg/network/web';
import * as storage from '@buoy-gg/storage/web';
import * as externalSync from '@buoy-gg/external-sync/web';
const modules = { network, storage, 'external-sync': externalSync };
<BuoyDevTools modules={modules} signIn />
import * as network from '@buoy-gg/network/web';
import * as storage from '@buoy-gg/storage/web';
import * as externalSync from '@buoy-gg/external-sync/web';
const modules = { network, storage, 'external-sync': externalSync };
<BuoyDevTools modules={modules} signIn />
With modules, Buoy loads just those tools.
Pass modules={{}} to load none.
Install the ones you want. The plugin adds them.
npm install @buoy-gg/clock @buoy-gg/lifecycle @buoy-gg/location @buoy-gg/permissions @buoy-gg/notifications
npm install @buoy-gg/clock @buoy-gg/lifecycle @buoy-gg/location @buoy-gg/permissions @buoy-gg/notifications
Clock changes JavaScript dates and timers in your app. It does not change the phone's clock.
Use Lifecycle to send App events to your app.
These include appStateChange, pause, resume and appUrlOpen.
Android also gets backButton. Relaunch reloads the page.
It sends visibilitychange and can set Device plugin battery data.
Location answers @capacitor/geolocation and navigator.geolocation calls.
Permissions can answer plugin checks and requests with test states.
Known names and test prompts are in the
plugin tools guide.
Names Buoy does not know still reach the phone.
Push saves events your push and local push listeners get.
It works with @capacitor/push-notifications and @capacitor/local-notifications.
Buoy adds no push listener of its own.
It cannot take the tap that opened your app.
Add @capacitor/app and @capacitor/device to read app details.
They help Desktop and MCP find the right simulator.
Your app still needs the plugins its own code uses.
With signIn, Buoy shows a QR code and short code.
Open the code page. Allow the sign-in there.
You can do this on any device with a browser.
Buoy uses your bundle id to name the app.
Set signIn={{ appId: 'com.example.app' }} to choose one.
Find it as app: plus that id in your
Sites list.
For hosted Ask Buoy, add its package. It needs Pro and a real Buoy sign-in. A key alone does not grant hosted chat access.
npm install @buoy-gg/ask-buoy
npm install @buoy-gg/ask-buoy
<BuoyDevTools signIn />
<BuoyDevTools signIn />
You can also use a dev token for other tools.
Run npx --package=@buoy-gg/core buoy login in your app folder.
It writes the token to .env.development.local as VITE_BUOY_KEY.
BuoyDevTools reads it when your app runs from the Vite dev server.
That is the browser, or the phone with live reload.
A vite build leaves that file out, so a phone build from it has no key.
Use signIn for those builds.
Plan limits still apply to each tool and action.
Install @buoy-gg/external-sync, as in the install step.
Open Buoy Desktop and sign in there too.
Set up MCP for your editor if you need it.
MCP uses the sign-in from buoy login on your computer. Free has the basic MCP and Buoy Optimize. Pro adds the full MCP.
Run list_devices and pick your app before using tools.
It shows as ios or android with a saved device ID.
| Where your app runs | Desktop address |
|---|---|
| iOS Simulator | The default works: http://localhost:42831. |
| Android emulator | Buoy uses http://10.0.2.2:42831. Allow web calls below. |
| Android phone on USB | Run adb reverse tcp:42831 tcp:42831. Use localhost. |
Live reload with server.url | Buoy uses the dev server's host. |
| Phone on Wi-Fi | Set socketURL to your Mac's LAN address. |
Android with a custom server.hostname | Set socketURL yourself. |
For a phone on Wi-Fi, use your own Mac's address:
<BuoyDevTools signIn
externalSync={{ socketURL: 'http://192.168.1.20:42831' }} />
<BuoyDevTools signIn
externalSync={{ socketURL: 'http://192.168.1.20:42831' }} />
The phone must be able to reach that Mac. Android can block plain HTTP and WebSocket calls. Use these settings for debug builds only:
// capacitor.config.ts
const config: CapacitorConfig = {
// ...your app settings
server: { cleartext: true },
android: { allowMixedContent: true },
};
// capacitor.config.ts
const config: CapacitorConfig = {
// ...your app settings
server: { cleartext: true },
android: { allowMixedContent: true },
};
Run npx cap sync after you change the settings.
iOS LAN calls may need NSAllowsLocalNetworking in Info.plist.
Keep that app network setting scoped to debug use too.
Release sync needs Pro and enableInRelease: true.
A plain HTTP LAN address also needs allowInsecureNetwork: true.
See release rules before you enable it.
BuoyDevTools hides Buoy in release builds. Pass enabled to show it.
Keep names so render tools can show your component names. Use source maps so JS Top can show files and lines. Add the asset plugin to list files before they load.
npm install @buoy-gg/assets
npm install @buoy-gg/assets
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { buoy } from '@buoy-gg/core/vite';
import { buoyAssets } from '@buoy-gg/assets/vite';
export default defineConfig({
plugins: [react(), buoy(), buoyAssets()],
esbuild: { keepNames: true },
build: { sourcemap: true },
});
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { buoy } from '@buoy-gg/core/vite';
import { buoyAssets } from '@buoy-gg/assets/vite';
export default defineConfig({
plugins: [react(), buoy(), buoyAssets()],
esbuild: { keepNames: true },
build: { sourcemap: true },
});
Use source maps in debug builds for this setup.
buoy() loads the asset list into Assets for you.
Vite builds list emitted files and media from public.
In Vite dev, source files show up as they load.
See asset setup for more build options.
The menu can move, hide, and bring tools back.
Web tools use the same panels as the native tools.
Network sees page fetch and XHR calls.
Storage reads Preferences, localStorage and sessionStorage.
Events can list phone plugin calls with secret values hidden.
State tools, Routes, Time Machine and Highlight have web builds.
Assets and Ask Buoy are supported in Beta too.
See the web tool list for each setup.
Sentry's code was tested, but its package is held back.
It is not part of this npm release.
The same Detox suites ran on Chrome and Android. Env and Minimize passed all checks. So did Network. React Query, Redux and Zustand passed all checks too. Floating and Sentry passed too. Ask Buoy passed all checks on both targets. Other suites have fails or blocked checks. New runs use a fake Pro token from license tests. Storage, Assets and Ask Buoy can now run Pro checks. Account passed all three paid-cache checks with a real key. Two old Account checks still fail on both targets. Some tests also ask for native data that Vite lacks. Events leaves Buoy's own clicks, web calls and logs out. App plugin calls still show. Ask Buoy saves a waiting card right away. Highlight filters use their own scroll view on web. The iPhone checks were by hand and MCP. They did not use the Detox runner.
matchMedia listeners only. CSS and the phone's theme keep their real mode.RCTView do not name web nodes.Real phones over LAN still need more checks. Capacitor 6 and 8 also need more tests.
Open an issue with steps to try. Name the tool and share what you saw. Share the Buoy and Capacitor versions you used. Name the phone and its OS too. Say if you used a debug or release build. For sync, say if you used USB or Wi-Fi. Share a small test app if you can. Remove keys, tokens, and private app data first.