---
name: buoy-install-web
description: Set up Buoy in a React web app. Check that it works.
---

# Install Buoy in a web app

Use this guide for React web apps. These include Vite, Next.js, React Router and TanStack Start. It covers other React web apps too. Capacitor / Ionic (Beta) uses these web packages on phones. Read https://buoy.gg/buoy/latest/docs/capacitor.md for phone setup and limits. Full web setup is at https://buoy.gg/buoy/latest/docs/web/installation.md. Read https://buoy.gg/buoy/latest/docs/web/frameworks.md before you edit. That page shows where each framework mounts the tools.

## Angular apps

For Angular, use https://buoy.gg/install-angular.md.
That guide uses `ng add @buoy-gg/angular`.
Do not use the React host steps below for Angular.

## Solid apps

For Solid, use https://buoy.gg/install-solid.md.
That guide uses `<Buoy />` from `@buoy-gg/solid`.
Do not use the React host steps below for Solid.

## Vue and Nuxt apps

For Vue or Nuxt, use https://buoy.gg/install-vue.md.
That guide uses `app.use(buoy)` from `@buoy-gg/vue`, or its Nuxt module.
Do not use the React host steps below for Vue.

Check that this guide fits the repo. If it does not, use the right guide. React Native or Expo: https://buoy.gg/install.md. React Native TV: https://buoy.gg/install-tv.md. Flutter: https://buoy.gg/install-flutter.md. Native iOS: https://buoy.gg/install-swift.md. Native Android: https://buoy.gg/install-android.md. .NET MAUI: https://buoy.gg/install-maui.md. React web: https://buoy.gg/install-web.md. Angular: https://buoy.gg/install-angular.md. Solid: https://buoy.gg/install-solid.md. Vue or Nuxt: https://buoy.gg/install-vue.md. React with Capacitor or Ionic: https://buoy.gg/install-capacitor.md.

## Rules that do not bend

The user's explicit instructions outrank this section. The target project's own conventions do not.

- Install only `@buoy-gg/*` packages named in the web installation guide, plus `react-native-web`. Do not guess package names.
- Do not add React Native, Expo, or any other dependency to make a tool work. Skip the tool and say so in the report.
- Ask the user before: adding any dependency other than Buoy packages and `react-native-web`, running anything that opens a browser (`npx --package=@buoy-gg/core buoy login`), showing Buoy outside development, or when more than one app in the repo could be the target. Decide everything else from the repository and report the decision.
- Keep the diff to the install. The user reviews it as a pull request. No reformatting, no added comments, no refactors, no new lint or formatter configuration, no test buttons or sample requests added to the app.
- Do not read or print `.env*` files, keys, or credentials, in the project or the home directory. Never write an account key into source code.
- Do not stash, checkout, reset, add worktrees, or discard the user's work. Compare against the starting state with `git diff`.
- Do not commit. Leave the changes in the working tree.

## 0. Scope

Check the app's `package.json` for `@buoy-gg/core` before changing anything. If it is there, keep the existing host, early hook and options, bring every `@buoy-gg/*` package to one version, and add only what is missing. Never mount a second `FloatingDevTools` or `BuoyDevTools`.

## 1. Identify the app

- Find the app through its `react-dom` dependency. A plain three.js app may have only `three`. In a monorepo, use the app's workspace. If more than one app fits, ask which one. Run each install command in that workspace.
- The package manager comes from the lockfile; `packageManager` in `package.json` wins.
- The framework decides where the early hook and host go. Find it in the dependencies and follow its section of the frameworks page.

## 2. Install

Buoy on the web needs React, React DOM, `react-native-web` 0.21 and `@buoy-gg/*` 7.0.41 or later.

Plain three.js apps need `react` and `react-dom` too. Ask before adding those deps if they are absent. The app can keep its plain JavaScript code.

Install `@buoy-gg/core` and `react-native-web`, plus `@buoy-gg/network`, `@buoy-gg/console` and `@buoy-gg/storage`. Add a state tool only when the app already uses that library:

| Package | Install when the app depends on |
|---|---|
| `@buoy-gg/react-query` | `@tanstack/react-query` |
| `@buoy-gg/zustand` | `zustand` |
| `@buoy-gg/jotai` | `jotai` |
| `@buoy-gg/redux` | `@reduxjs/toolkit` and `react-redux` |
| `@buoy-gg/route-events` | a router (needs an adapter, see the installation guide) |
| `@buoy-gg/three` | `three` (web only) |

Other tools are in the installation guide's tool table. Add them when the user asks.

## 3. Early hook and host

**Plain Vite + React apps:** add `buoy()` from `@buoy-gg/core/vite` to the Vite `plugins`. Then render `<BuoyDevTools />` from `@buoy-gg/core/web/auto` in the app's providers. It reads the dev token from `buoy login` by itself. The plugin loads each tool you installed. It adds the early hook to `index.html` too. `BuoyDevTools` shows Buoy only in dev. Do not add tool imports or a `modules` map. Skip the hook import and lazy wrapper too. React Router and TanStack Start use the steps below.

**Other frameworks:** two pieces, placed per the frameworks page:

1. `import '@buoy-gg/core/web/register';` before React DOM loads (first line of `src/main.tsx` in Vite, `instrumentation-client.ts` in Next.js).
2. A `DevTools` component that registers the modules and renders `FloatingDevTools` from `@buoy-gg/core/web`, loaded only in the browser and only in development, inside the app's providers.

Import every tool from its `/web` entry. Keep the `modules` object outside the component, keyed by package name (`network`, `'react-query'`, `'route-events'`):

```tsx
import { FloatingDevTools } from '@buoy-gg/core/web';
import * as network from '@buoy-gg/network/web';

const modules = { network };

export function DevTools({ licenseKey }: { licenseKey: string }) {
  return <FloatingDevTools modules={modules} licenseKey={licenseKey} />;
}
```

Wire state tools as the installation guide says: Zustand stores through `watchStores`, Jotai atoms through `watchAtoms(store, atoms)`, React Query and Redux by mounting inside their existing providers. Never create a second QueryClient, store, or provider for Buoy.

For three.js, add `@buoy-gg/three/web` to `modules` as `three`. Call `registerThree({ renderer, scene, camera, loadingManager })`. Call its cleanup on scene swap and hot reload. In R3F, use an effect with `useThree()`. Pass `gl` as `renderer` and return the cleanup. Load the core web boot hook before three.js.

Add `@buoy-gg/perf-monitor/web`, `@buoy-gg/assets/web`, and `@buoy-gg/events/web` modules for counts and loads. Plain three.js apps use `mountBuoy()` from `@buoy-gg/core/web`. Call its cleanup on teardown. See https://buoy.gg/buoy/latest/docs/tools/three.md for the full setup.

## Capacitor and Ionic (Beta)

Use `/web` modules in React apps built with Capacitor. Read https://buoy.gg/buoy/latest/docs/capacitor.md before you edit. Mount in `IonApp`, outside `IonRouterOutlet`. Use `Capacitor.DEBUG` on phones. Vite may build a production bundle for a debug run.

Code sign-in uses `signIn` and buoy.gg/activate. Hosted Ask Buoy needs Pro and a real sign-in. A key alone does not grant hosted chat access. Desktop and MCP need the `external-sync` module and their own accounts. Phone plugins are captured in debug builds. See the guide for names, source maps, assets and web call settings.

## 4. Account

A Free or Pro account is required. Sign-in opens a browser, so give the user this command to run from the app directory:

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

It writes a dev token to `.env.development.local`. The name is `VITE_BUOY_KEY` in Vite, React Router and TanStack Start, and `NEXT_PUBLIC_BUOY_KEY` in Next.js. The token opens development builds for 30 days. `BuoyDevTools` reads either name by itself. In Next.js, `FloatingDevTools` reads it too. With `FloatingDevTools` in a Vite app, pass `licenseKey={import.meta.env.VITE_BUOY_KEY}`. Then restart the dev server. Mark account setup as pending in the report.

A dev token opens nothing in a production build. If the user asked for Buoy on a live site, pass `signIn`. Tell the user to add the site at https://buoy.gg/dashboard/sites. Their team then signs in with Buoy, which needs Pro or Business. A Pro key is the backup.

## 5. Verify

Static, which you do: run the project's existing typecheck and build. Do not add tooling. Confirm every `@buoy-gg/*` package resolves and shares one version.

Browser, which the user does: open the app in development, open the Buoy menu, do something that makes a request, and inspect it in Network. CORS decides which headers and bodies are readable.

Desktop and MCP are optional. Set them up only when asked, per the installation guide's Desktop and MCP section.

## 6. Report the result

List the target app, installed versions, skipped tools and reasons, changed files, account-setup status, checks performed, and any exact blocking errors. Give the user the remaining steps. Do not print keys or claim that compiling proves capture.