Genie React

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 init

init 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:

vite.config.ts
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:

app/layout.tsx
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>
  )
}
instrumentation.ts
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 />:

app/genie-query-tools.tsx
'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:

genie-hook.ts
if (__DEV__) require('genie-react/hook')
index.ts
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 4390

In 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:

src/store.ts
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 15000
connected: 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

ImportUse
genie-react<Genie /> and app tool hooks
genie-react/viteVite plugin with the hub built in
genie-react/nextGenieScript and registerGenie for Next.js
genie-react/nativeReact Native and Expo component
genie-react/hookThe DevTools hook for manual setups
genie-react/client, genie-react/collectorsA hand-built client and its collectors
genie-react/toolsApp tool hooks without TanStack imports
@genie-react/cliThe 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.

On this page