Setup Guide

Get Relens running end-to-end in your project. After this guide, both you and your AI coding agent will have everything needed to find, fix, and verify React performance issues.

Prerequisites: Node.js 18+, Chrome browser, an AI agent with MCP support (e.g., Claude Code)

Install the npm package

Add relens to your React app and wrap your component tree:

App.tsx

import { RelensProvider } from 'relens';

function App() {
  return (
    <RelensProvider
      instanceId="my-app"   // routing key — must match MCP config
      network={true}         // opt-in fetch/XHR interception
    >
      <YourApp />
    </RelensProvider>
  );
}

Provider props

Prop	Default	Description
instanceId	—	Routing key linking your app to the MCP endpoint. Must match the URL in .mcp.json.
enabled	true	Set to false for zero overhead (renders a Fragment).
network	false	Enable fetch/XHR interception for network telemetry.
userEvents	false	Enable user interaction capture (clicks, input, scroll).
maxEntries	2000	Ring buffer cap. Oldest entries evicted when full.
sampleRate	1.0	Probability (0.0-1.0) of recording each render.
filter	—	Function (componentId: string) => boolean to filter components.

Install the Chrome extension

The extension is not yet on the Chrome Web Store. Load it as an unpacked extension:

cd chrome-extension
yarn install
yarn build

Navigate to chrome://extensions
Enable "Developer mode" (toggle in top-right)
Click "Load unpacked"
Select the chrome-extension/ directory

A green dot in the popup means the server connection is active.

Start the server

The server receives telemetry from the extension and exposes MCP tools to your AI agent.

cd server
yarn install
yarn build
yarn start

You should see: [relens] Server listening on port 9229

Configure your AI agent

Add the MCP server to your project's .mcp.json:

.mcp.json

{
  "mcpServers": {
    "relens": {
      "type": "http",
      "url": "http://localhost:9229/mcp/i/my-app"
    }
  }
}

The instanceId in the URL (my-app) must match the instanceId prop on your provider.

Verify the pipeline

Start your React app, open it in Chrome, and interact with it. Then ask your AI agent to call:

> connection_status

{
  "status": "connected",
  "tabCount": 1,
  "totalRenders": 42
}

If you see renders, everything is working. Try get_slow_components or run_performance_audit to see real performance data.

Troubleshooting

Symptom	Fix
Extension shows "disconnected"	Start the server: cd server && yarn start. Check lsof -i :9229 for port conflicts.
connection_status shows 0 renders	Reload the extension in chrome://extensions, then hard-refresh the app page.
Component names show as profiler ID	Stale npm-package in node_modules. Run: yarn install --force && rm -rf node_modules/.vite
Network tools return empty	Add network={true} to <RelensProvider>.
MCP tools timeout	Restart the server, then reconnect in your AI agent.