Axonpack

Reference

Every export, and every option each one takes.

ReactNativeDevtoolsPanel

The app's side of React Native DevTools. A single object, because an app has exactly one debugger connection. Usable immediately: anything sent before somebody opens DevTools is kept and flushed when they do, and a release build has no connection at all, so it stays quiet.

import { ReactNativeDevtoolsPanel } from "@axonpack/react-native-devtools-tab";

const tab = ReactNativeDevtoolsPanel.registerTab(options: TabOptions): RegisteredTab;

Call it once per tab, as many times as you have tabs.

TabOptions

OptionTypeDefaultWhat it is
namestringrequiredThe label in the tab strip, and what the tab's id is built from
componentComponentTyperequiredWhat the tab draws, under the bar this package puts above it
iconstringthe Axonpack markA symbol shown after the tab's name

icon is text rather than an image because React Native DevTools' own icon slots take an element, and every way of putting one there loses its drawing. Any character works, so an emoji does too.

An id is derived from name rather than written by hand, and numbered if two tabs share a name. It is also the DevTools panel's own id, so a reload lands on the tab that is already open instead of leaving a dead one in the strip beside a new one.

RegisteredTab

What registerTab returns.

MemberTypeWhat it does
focus()() => voidShows this tab in a DevTools window that is already open, and in the next one that connects

Call focus() just before opening DevTools from the app, for example with DevSettings's openDebugger, and the window lands on the tab instead of on Console. On iOS nothing else can choose the panel: openDebugger takes no argument, and DevTools picks its starting panel before any tab of yours has been added.

import { TurboModuleRegistry } from "react-native";

const tab = ReactNativeDevtoolsPanel.registerTab({
  name: "Session",
  component: Session,
});

// Later, from a button in the app, in a debug build:
tab.focus();
// React Native's own DevSettings: openDebugger is what the dev menu's Open DevTools calls.
TurboModuleRegistry.get<{ openDebugger?: () => void }>(
  "DevSettings",
)?.openDebugger?.();

COPY_ATTRIBUTE

import { COPY_ATTRIBUTE } from "@axonpack/react-native-devtools-tab";

<button {...{ [COPY_ATTRIBUTE]: text }}>Copy</button>;

An element carrying it has its value copied to the clipboard of the computer DevTools runs on when it is clicked, and a short note in the tab says whether that worked. Any onClick on the element still runs, after the copy.

A handler runs in the app, so a copy written the ordinary way, with the app's own clipboard module, lands on the device's clipboard, which a phone does not share with the computer. This is the way to put text on the computer's.

withReactNativeDevtoolsTab

The Metro side. One line in metro.config.js, and the tab is served.

const {
  withReactNativeDevtoolsTab,
} = require("@axonpack/react-native-devtools-tab/metro");

withReactNativeDevtoolsTab(config, options?);

Options

OptionTypeDefaultWhat it is
frontendPathstringdiscoveredWhere React Native DevTools' own files are, for a layout this cannot work out for itself

See Troubleshooting for how to find that path and when you need it.

Calling the app from a terminal

A script or an AI agent on the computer running Metro can call into the app through the DevTools window open on it. The window makes the call on its own debugger connection. On a React Native that allows one debugger per app (below 0.86, or Expo started headless), a second connection would close that window, so this is how a tool gets in without doing that. @axonpack/expo-devtools's devtools command line tool works this way on those versions.

The app puts an object on globalThis.__AXONPACK_AGENT__, and the tool posts to Metro:

curl -s http://127.0.0.1:8081/axonpack-rn-devtools-tab/agent \
  -d '{"page":"device=<id>&page=<id>","call":"run","arg":{"topic":"network"}}'

The window open on that page runs __AXONPACK_AGENT__.run({ topic: "network" }) and answers with its return value. page is the query string of the page's webSocketDebuggerUrl in Metro's /json/list.

The routes

Each path below is under /axonpack-rn-devtools-tab on Metro's port. The first two are for a tool; the last two are what the window's own script uses.

Method and pathBodyReply
GET /agentnone200, a JSON list of the page values a window is open on.
POST /agent{ "page": string, "call": string, "arg"?: object }200 with { "value": ... }, the return value as JSON, or { "error": "..." } when the call threw.
GET /agent/window?page=noneAn event stream the window holds open. Each event is a call for it to make.
POST /agent/reply?id=The window's answer to call id204. The answer goes to whoever is waiting on that call.

call names one of the object's own methods, and arg is one JSON object or nothing. The window builds the call from them, so nothing else is ever evaluated.

StatusErrorWhen
400expected { page, call, arg }: a method name and a JSON objectThe body is not such a call.
403this computer onlyThe request came from another address, or from a web page whose Origin or Host isn't localhost.
404no DevTools window is open on this pageNo window from Metro's shortcut is open on that page. A tool then knows there is none of ours to close.
404no such routeAny other method or path.
413a call is at most 64 KBThe call is over 64 KB.
502the reply was over 64 MBThe window's answer was too big to pass on.

Only a window opened from Metro's shortcut registers, since that is the one this package serves. A call waits while JS is paused at a breakpoint and the route has no timeout of its own, so give the request one.

How it works

React Native DevTools is a Chrome DevTools frontend fork, served by @react-native/dev-middleware. This package serves that same frontend from its own route, adds a nonce to the page's CSP and injects one script, and that script re-imports the frontend's own modules to reach InspectorView.addPanel. The tab's body is an iframe, and it reaches the device over the debugger connection the frontend already has, tagged with the tab's own id so it never crosses React DevTools' own traffic.

Inside that iframe is a custom React reconciler's other half. The app's React commits produce a list of changes (create this node, move that one, set these props) and the page replays them onto real elements. A function prop cannot be sent, so each is swapped for the position it sits at in the tree; the page calls back with that position and the app runs the closure it stands for.

On this page