Install and connect
Add Genie to a Vite, Next.js, React Native or other React app and check the connection.
You need a development build of React 18 or newer and Node.js 22.12 or newer.
Install
From the app folder:
pnpm add -D genie-react @genie-react/cli
npx @genie-react/cli initinit wires Vite and Next.js and installs the agent skill. init --dry-run previews the changes,
and manualSteps lists what is left for you. Then follow the section for your framework.
Vite and TanStack Start
init adds the plugin, which runs Genie's hub inside the dev server:
import { defineConfig } from 'vite'
import { genie } from 'genie-react/vite'
export default defineConfig({
plugins: [genie()],
})Render <Genie /> once inside your Query and Router providers to add their tools:
import { Genie } from 'genie-react'
{import.meta.env.DEV && <Genie />}Outside the providers, pass them in: <Genie queryClient={queryClient} router={router} />.
Production builds leave Genie out.
Next.js
init adds GenieScript to the root layout and creates instrumentation.ts, which starts the hub:
import { GenieScript } from 'genie-react/next'
import type { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<body>
<GenieScript />
{children}
</body>
</html>
)
}export async function register(): Promise<void> {
if (process.env.NODE_ENV !== 'production' && process.env.NEXT_RUNTIME === 'nodejs') {
const { registerGenie } = await import('genie-react/next')
await registerGenie()
}
}For Query tools, register your QueryClientProvider's client. Render this after <GenieScript />:
'use client'
import { useEffect } from 'react'
import { queryClient } from './query-client'
export function GenieQueryTools() {
useEffect(() => {
if (process.env.NODE_ENV === 'production') return
let unregister: (() => void) | undefined
let cancelled = false
void Promise.all([import('genie-react/collectors/query'), import('genie-react/protocol')]).then(
([{ queryCollector }, { registerGenieCollector }]) => {
if (!cancelled) unregister = registerGenieCollector(queryCollector(queryClient))
},
)
return () => {
cancelled = true
unregister?.()
}
}, [])
return null
}apps/next-demo shows the full setup.
React Native and Expo
Load the DevTools hook before React, from its own module so the import is not hoisted past the if:
if (__DEV__) require('genie-react/hook')import './genie-hook'
import { registerRootComponent } from 'expo'Mount Genie once near the root. AppState lets verify see when the app went to the background:
import { AppState } from 'react-native'
const DevGenie = __DEV__
? (require('genie-react/native') as typeof import('genie-react/native')).Genie
: () => null
<DevGenie
appName="My app"
url="ws://127.0.0.1:4390/__genie/ws"
queryClient={queryClient}
appState={AppState}
/>Run npx @genie-react/cli hub --port 4390 on your machine. The iOS Simulator reaches it at
ws://127.0.0.1:4390/__genie/ws, the Android Emulator at ws://10.0.2.2:4390/__genie/ws, and a
physical device through a port forward. React Navigation and Expo Router need
app tools for navigation. See examples/expo-demo.
Other bundlers
For webpack, Rspack, esbuild, Parcel and others, run the standalone hub:
npx @genie-react/cli hub --port 4390In development only, load its client first in the document head:
<script src="http://127.0.0.1:4390/__genie/client.js"></script>To bundle the client instead, import genie-react/hook before React and start one client:
import 'genie-react/hook'
import { createGenieClient, reactCollector, sessionCollector } from 'genie-react/client'
import { defaultAppCollectors } from 'genie-react/collectors'
import { queryClient } from './query-client'
createGenieClient({
url: 'ws://127.0.0.1:4390/__genie/ws',
collectors: [sessionCollector(), reactCollector(), ...defaultAppCollectors({ queryClient })],
}).start()defaultAppCollectors returns the collectors <Genie /> registers. It takes optional queryClient,
router and reduxStore; without TanStack Query, call defaultAppCollectors() and drop the
queryClient import. Add your own collectors after it in the same list.
A client that lists every collector by hand misses the ones a new release adds. Without
requestWatchCollector, verify cannot wait for the app's requests and refuses --domains network
at begin. Without visibilityCollector, verify reports the URL the app connected on, not the page
it is on.
Redux
Register the collector where you create the store:
import { configureStore } from '@reduxjs/toolkit'
import { reduxCollector } from 'genie-react/collectors/redux'
export const store = configureStore({ reducer })
export const genieRedux = reduxCollector(store, { name: 'app' })Then pass reduxStore={store} to <Genie /> on Vite or React Native, add genieRedux to a
bundled client's collectors, or call registerGenieCollector(genieRedux) on Next.js. This adds
the Redux tools.
The second argument is optional: name labels the store, historyLimit sets how many records the
history keeps (1 to 5000, default 500), recordLibraryActions: true keeps RTK Query's own actions
as records instead of counting them, and detectMutations: false turns off the in-place mutation
check. <Genie reduxStore={store} /> uses the defaults unless reduxCollector already ran for that
store.
Check the connection
Start the dev server, open the app in an agent-browser session, and wait for Genie. This is
apps/vite-demo; use your own URL:
agent-browser --session my-agent open http://localhost:3040/
npx @genie-react/cli status --session my-agent --wait 15000connected: true
ready: true
app: {name:vite-demo,url:http://localhost:3040/,reactVersion:19.2.7,reactMounted:true}
domains: [session,react,app,memory,perf,plugin,timeline,query]domains lists the tool groups. If status fails, run npx @genie-react/cli doctor --live or see
troubleshooting.
Packages
| Import | Use |
|---|---|
genie-react | <Genie /> and app tool hooks |
genie-react/vite | Vite plugin with the hub built in |
genie-react/next | GenieScript and registerGenie for Next.js |
genie-react/native | React Native and Expo component |
genie-react/hook | The DevTools hook for manual setups |
genie-react/client, genie-react/collectors | A hand-built client and its collectors |
genie-react/tools | App tool hooks without TanStack imports |
@genie-react/cli | The genie-react command |
Supported peers: React 18+, Vite 5+, TanStack Query 5+, TanStack Router 1+, Redux 4 and 5, and Redux Toolkit 1.9 and 2.