---
name: buoy-install-solid
description: Add Buoy to a Solid app. Pick tools, sign in, and check the app.
---

# Install Buoy in Solid (Beta)

Read https://buoy.gg/buoy/latest/docs/web/solid.md first.
Use this guide for Solid 1.8 and 1.9 apps built with Vite.
Solid 2 is not supported yet. Stop and tell the user.
React web apps use https://buoy.gg/install-web.md instead.
Angular uses https://buoy.gg/install-angular.md.
React Native uses https://buoy.gg/install.md.

## Rules

The user's own instructions come first.
Keep the diff small. Do not commit or discard work.
Do not read or print keys or env files.
Do not add React Native or Expo.
Do not make a new store or QueryClient for Buoy.
Keep one `<Buoy />`. Keep its app options and links.
Ask before you add deps other than Buoy packages.
React Query is the one peer you may add for Solid Query.
Ask before you open a browser or create an account.
Ask before you show Buoy in a release build.
Ask which app to use if more than one fits.
Choose the rest from the repo and say what you chose.

## 1. Find the app

Look for `solid-js` and `vite-plugin-solid` in the app's `package.json`.
Check that `solid-js` is 1.8 or 1.9.
Use the app folder, not the monorepo root.
Use the package manager set in `package.json` or its lockfile.

Check for an existing `<Buoy />` or `startBuoy` call.
If one exists, repair that setup. Do not add another.
Keep all Buoy packages on one release.

## 2. Add Buoy

Install these as dev deps in the app folder:
`@buoy-gg/core`, `@buoy-gg/solid`, `@buoy-gg/network`,
`@buoy-gg/storage`, `@buoy-gg/console` and `@buoy-gg/external-sync`.

Add a tool when the app has its library:

| Package | Add when the app has |
|---|---|
| `@buoy-gg/route-events` | `@solidjs/router` |
| `@buoy-gg/react-query` and `@tanstack/react-query` | `@tanstack/solid-query` |
| `@buoy-gg/zustand` | `zustand`, or Solid stores to show |
| `@buoy-gg/redux` | `@reduxjs/toolkit` |
| `@buoy-gg/jotai` | `jotai` |
| `@buoy-gg/highlight-updates` | any Solid app |

Give `@tanstack/react-query` the same version as `@tanstack/solid-query`.
Add other tools when the user asks.

## 3. Plugin and host

Add `buoy()` from `@buoy-gg/core/vite` after `solid()` in the Vite plugins.
It finds the tools and adds the early hook to `index.html`.
Do not add tool imports, a `modules` map, or a hook import.

```ts
import { buoy } from '@buoy-gg/core/vite';

export default defineConfig({ plugins: [solid(), buoy()] });
```

SolidStart: add `buoy()` after `solidStart()`.
It has no `index.html`, so the plugin can't add the hook.
Put `import '@buoy-gg/solid/register';` first in `entry-client.tsx`.
Load early tools there with `await import()`.
Load `@solidjs/start/client` last, with `await import()` too.
If it loads first, it makes the store too soon.
Then Redux can't see it.

Render `<Buoy />` from `@buoy-gg/solid` once.
Put it in the router's `root` layout, inside `QueryClientProvider`.
With no router, put it next to the app's root.
It runs in dev builds only, so add no guard of your own.

Name routes with `info={{ name }}` only if the user asks.
Show Solid stores with `buoySolidStore` from `@buoy-gg/solid/store`.
Pass them in `zustandStores`. Pass vanilla Zustand stores as they are.
Redux: load `@buoy-gg/redux/web` before the app makes its store.
Jotai: pass the app's atoms to `watchAtoms` from `@buoy-gg/jotai/web`.
Put app settings for Buoy in their own file, loaded with `load` behind a dev check.

## 4. Sign in

With consent, run this in the app folder:

```sh
npx buoy login
```

If consent is not given, leave this step for the user.
The CLI writes `VITE_BUOY_KEY` to a file that Git ignores.
`<Buoy />` reads it. Never paste a key in code.

## 5. Run the app

Use the app's own dev script.
Keep an existing dev server if it serves this app.
Restart it after adding a tool or signing in.
Do not stop a server owned by someone else.

## 6. Verify

Static: run the app's own checks and build script.
Do not add test tools or run TypeScript by hand.
Check that Buoy packages resolve on one release line.
Check that `<Buoy />` appears once.
Check prod output: no Buoy tools and no React DOM.
If the app's typecheck fails on Buoy's React types, say so.
The Solid guide's TypeScript section has the fix.

Browser: with consent, open the app and the Buoy dial.
If not allowed, give the user these steps to do.
Open Network. Use the app to make a web call.
Find that call in Network. CORS still applies.
A build alone does not prove that capture works.

Desktop and MCP are optional. Set them up only if asked.

## 7. Report

List the app, tools, versions, changed files, and checks.
Say which tools you skipped and why.
Say if sign-in or browser checks still need the user.
Give the exact errors and any steps left to do.
Keep keys and tokens out of the report.