React Bridge (@3lens/react-bridge)

The React bridge provides seamless integration between 3Lens devtools and React applications, with first-class support for React Three Fiber (R3F).

Installation

npm install @3lens/react-bridge @3lens/core
# or
pnpm add @3lens/react-bridge @3lens/core
# or
yarn add @3lens/react-bridge @3lens/core
# or
bun add @3lens/react-bridge @3lens/core

For R3F support:

npm install @react-three/fiber three

Quick Start

With React Three Fiber

import { ThreeLensCanvas, useDevtoolEntity } from '@3lens/react-bridge';

function App() {
  return (
    <ThreeLensCanvas threeLensConfig={{ appName: 'My App' }}>
      <Scene />
    </ThreeLensCanvas>
  );
}

With Vanilla Three.js

import { ThreeLensProvider, useThreeLensProbe } from '@3lens/react-bridge';

function App() {
  return (
    <ThreeLensProvider config={{ appName: 'My App' }}>
      <ThreeCanvas />
    </ThreeLensProvider>
  );
}

API Reference

Provider & Context

Export	Description
ThreeLensProvider	Main context provider
ThreeLensContext	React context object

Hooks

Hook	Description
useThreeLensProbe	Access the probe instance
useThreeLensProbeOptional	Safe probe access
useSelectedObject	Selection state and controls
useDevtoolEntity	Register named entities
useDevtoolEntityGroup	Register entity groups
useMetric	Extract custom metrics
useFPS	FPS metric shortcut
useFrameTime	Frame time metric
useDrawCalls	Draw calls metric
useTriangles	Triangle count metric
useGPUMemory	GPU memory metric
useTextureCount	Texture count metric
useGeometryCount	Geometry count metric

React Three Fiber Integration

Export	Description
ThreeLensCanvas	Drop-in Canvas replacement
createR3FConnector	Manual R3F connection
R3FProbe	R3F probe component
useR3FConnection	Manual connection hook

Types

Type	Description
ThreeLensProviderConfig	Provider configuration
ThreeLensContextValue	Context value interface
UseMetricOptions	Metric hook options
MetricValue<T>	Metric return value
EntityOptions	Entity registration options
RegisteredEntity	Registered entity info

Usage Patterns

Basic Performance Monitoring

import { ThreeLensProvider, useFPS, useDrawCalls } from '@3lens/react-bridge';

function Stats() {
  const fps = useFPS();
  const drawCalls = useDrawCalls();
  
  return (
    <div>
      <span>FPS: {fps.current.toFixed(0)}</span>
      <span>Draw Calls: {drawCalls.current}</span>
    </div>
  );
}

function App() {
  return (
    <ThreeLensProvider>
      <Canvas />
      <Stats />
    </ThreeLensProvider>
  );
}

Named Entity Registration

import { useDevtoolEntity } from '@3lens/react-bridge';

function Enemy({ id, health }) {
  const ref = useRef<THREE.Mesh>(null);
  
  useDevtoolEntity(ref.current, {
    name: `Enemy_${id}`,
    module: 'game/enemies',
    metadata: { health },
    tags: ['enemy', 'ai-controlled'],
  });
  
  return <mesh ref={ref}>...</mesh>;
}

Selection Handling

import { useSelectedObject } from '@3lens/react-bridge';

function Inspector() {
  const { selectedNode, hasSelection, clear } = useSelectedObject();
  
  if (!hasSelection) return <p>Select an object</p>;
  
  return (
    <div>
      <h3>{selectedNode?.ref.name}</h3>
      <button onClick={clear}>Deselect</button>
    </div>
  );
}

Related Documentation

• Getting Started Guide
• React/R3F Guide
• Core Package Documentation
• Overlay Package Documentation