@axonpack/react-native-devtools-tab 0.1.0

package/dist/renderer/static/js/index.8039fdb712.js.LICENSE.txt

@@ -0,0 +1,39 @@
+/**
+ * @license React
+ * react-dom-client.production.js
+ *
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @license React
+ * react-dom.production.js
+ *
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @license React
+ * react.production.js
+ *
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @license React
+ * scheduler.production.js
+ *
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@axonpack/react-native-devtools-tab",
+  "version": "0.1.0",
+  "description": "Put your own tab in React Native DevTools, with a two-way channel to the running app",
+  "author": "Md Asadujjaman <abappi2019@gmail.com> (https://github.com/abappi19)",
+  "keywords": [
+    "react-native",
+    "devtools",
+    "metro",
+    "expo",
+    "debugging"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axonpack/axonpack.git",
+    "directory": "packages/@axonpack/react-native-devtools-tab"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src/index.ts",
+    "src/core/constants",
+    "src/core/services/message-channel.service.ts",
+    "src/core/services/panel-channel.service.ts",
+    "src/core/services/tab-channel.service.ts",
+    "src/device",
+    "src/renderer/start-renderer.ts",
+    "src/renderer/services",
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./renderer": "./src/renderer/start-renderer.ts",
+    "./metro": "./dist/metro/index.cjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rsbuild build",
+    "prepare": "bun run build",
+    "example:expo": "bun run build && cd example && bun run expo",
+    "clean": "rm -rf dist",
+    "lint": "oxlint src",
+    "check-types": "tsc --noEmit",
+    "test": "bun run build && bun test src"
+  },
+  "devDependencies": {
+    "@rsbuild/core": "^2.2.7",
+    "@types/bun": "^1.3.14",
+    "@types/jsdom": "^21.1.7",
+    "@types/react": "~19.1.17",
+    "@types/react-dom": "~19.2.2",
+    "jsdom": "^20.0.3",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "react-native-web": "^0.21.2",
+    "react-reconciler": "0.33.0",
+    "typescript": "~5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "dependencies": {
+    "react-reconciler": "^0.33.0"
+  }
+}

package/src/core/constants/devtools.const.ts

@@ -0,0 +1,24 @@
+/**
+ * The one name the app's side and the dev server's side have to agree on.
+ *
+ * It names the HTTP route the panel is served from, and the domain messages are tagged with on the
+ * debugger connection. React Native's own integration uses `react-devtools` on that same channel, so
+ * having a name at all is what keeps the two apart.
+ *
+ * A constant rather than an option, because nothing makes it vary: the dispatcher is per JS runtime
+ * and each dev server has its own port, so two apps never share either. Only two independent
+ * devtools instances *inside one app* would need to differ, and there is no such case.
+ */
+export const DEVTOOLS_ID = "axonpack-rn-devtools";
+
+export const DEVTOOLS_ROUTE = `/${DEVTOOLS_ID}-tab`;
+
+/**
+ * Where the app keeps its tab list, for the frontend to read.
+ *
+ * A panel is built from what is on here, not from a message, so opening or reloading React Native
+ * DevTools finds the tabs that are already registered instead of having to be told about them again.
+ * The app has no way of knowing a frontend reloaded, and nothing re-announces, so a push alone left
+ * the tab strip empty until the app itself restarted.
+ */
+export const DEVTOOLS_TABS = `__${DEVTOOLS_ID}_tabs__`;

package/src/core/constants/message.const.ts

@@ -0,0 +1,28 @@
+/**
+ * Every message type on the wire, and what each carries.
+ *
+ * None of these name their tab, because the channel does. `createTabChannel` stamps the id on the
+ * way out and drops anything addressed elsewhere on the way in, so what actually crosses is the
+ * payload below plus that one field.
+ */
+
+import type { RemoteOp } from "./remote-op.const";
+
+/** App to panel, once per tab: the tab exists, and this is what to call it. */
+export const REGISTER = "tab:register";
+
+/** App to panel, on every render: what React just changed. */
+export const MUTATE = "tab:mutate";
+
+/** Panel to app: something in the tab was clicked, typed in, or otherwise acted on. */
+export const ACTION = "tab:action";
+
+/** Panel to app, on load: "describe yourself", since the app usually started first. */
+export const HELLO = "tab:hello";
+
+export type TabRegistration = { name: string; icon?: string };
+
+export type TabMutation = { ops: RemoteOp[] };
+
+/** `action` is the name a function prop was swapped for, not something anybody chose. */
+export type TabAction = { action: string; payload?: unknown };

package/src/core/constants/remote-op.const.ts

@@ -0,0 +1,37 @@
+/**
+ * What a rendered component looks like on the wire.
+ *
+ * The app runs React and the panel owns the DOM, so what crosses is neither a component nor a
+ * picture of one: it is the list of changes React just made, replayed against real nodes at the far
+ * end. Nodes are named by number, and the panel keeps its own map from those numbers to elements.
+ *
+ * Kept as mutations rather than as a fresh tree each render, because replacing the tree would take
+ * the focus and the caret out of whatever input the user is typing in.
+ */
+
+/** The container. Not an instance, so it has no id of its own. */
+export const ROOT = 0;
+
+export type RemoteProps = Record<string, unknown>;
+
+/** A function prop, which cannot cross. The panel calls back with this name instead. */
+export type RemoteHandler = { handler: string };
+
+export function isHandler(value: unknown): value is RemoteHandler {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as RemoteHandler).handler === "string"
+  );
+}
+
+export type RemoteOp =
+  | { op: "create"; id: number; type: string; props: RemoteProps }
+  | { op: "text"; id: number; text: string }
+  | { op: "append"; parent: number; child: number }
+  | { op: "insert"; parent: number; child: number; before: number }
+  | { op: "remove"; parent: number; child: number }
+  | { op: "update"; id: number; props: RemoteProps }
+  | { op: "retext"; id: number; text: string }
+  /** Everything the panel holds is stale: it is being sent the tree from the start. */
+  | { op: "clear" };

package/src/core/services/message-channel.service.ts

@@ -0,0 +1,87 @@
+/**
+ * A two-way message channel, with no opinion about what crosses it.
+ *
+ * Both ends of this library use it: the app's side and the panel's side are the same shape, because
+ * the panel is a separate JavaScript engine with no access to the app's memory. Everything it shows
+ * has to arrive as a message, and anything it wants the app to do has to go back the same way.
+ */
+
+export type MessageListener = (payload: unknown) => void;
+
+export type MessageChannel = {
+  /** Sends to the other end. Fire and forget. */
+  send: (type: string, payload?: unknown) => void;
+  /** Listens for what the other end sends. Call the returned function to stop. */
+  onMessage: (type: string, listener: MessageListener) => () => void;
+};
+
+/** The one envelope both ends agree on, so a transport only has to carry an object. */
+export type Envelope = { type: string; data: unknown };
+
+export function isEnvelope(value: unknown): value is Envelope {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { type?: unknown }).type === "string"
+  );
+}
+
+export type Transport = {
+  post: (envelope: Envelope) => void;
+  /** Called with whatever arrived; hand it anything, the channel checks the shape. */
+  subscribe: (deliver: (value: unknown) => void) => void;
+};
+
+/**
+ * Builds a channel over a transport.
+ *
+ * Messages sent before the transport is ready are kept rather than dropped, in the shape they will
+ * go out in: a panel is opened long after an app starts, and the first thing a caller does is
+ * usually to send the state it already has.
+ */
+export function createMessageChannel(
+  transport: Transport | null = null,
+): MessageChannel & {
+  attach: (transport: Transport) => void;
+} {
+  const listeners = new Map<string, Set<MessageListener>>();
+  const backlog: Envelope[] = [];
+  let active: Transport | null = null;
+
+  const attach = (next: Transport): void => {
+    active = next;
+    next.subscribe((value) => {
+      if (!isEnvelope(value)) return;
+      for (const listener of listeners.get(value.type) ?? [])
+        listener(value.data);
+    });
+    for (const envelope of backlog.splice(0)) next.post(envelope);
+  };
+
+  if (transport) attach(transport);
+
+  const channel = {
+    attach,
+
+    send(type: string, payload?: unknown) {
+      const envelope: Envelope = { type, data: payload };
+      if (!active) {
+        backlog.push(envelope);
+        return;
+      }
+      active.post(envelope);
+    },
+
+    onMessage(type: string, listener: MessageListener) {
+      const existing = listeners.get(type) ?? new Set<MessageListener>();
+      existing.add(listener);
+      listeners.set(type, existing);
+
+      return () => {
+        listeners.get(type)?.delete(listener);
+      };
+    },
+  };
+
+  return channel;
+}

package/src/core/services/panel-channel.service.ts

@@ -0,0 +1,29 @@
+import {
+  createMessageChannel,
+  type MessageChannel,
+} from "./message-channel.service";
+
+/**
+ * The browser end of the channel, for the page shown in a tab.
+ *
+ * The page is an iframe inside a DevTools panel, so messages to the app go up to the host script,
+ * which relays them over the debugger connection the frontend already has.
+ *
+ * In `core` rather than beside the renderer because it draws nothing. The renderer is built on it,
+ * and so is any page a consumer serves themselves.
+ */
+export function createPanelChannel(): MessageChannel {
+  const channel = createMessageChannel({
+    post: (envelope) => window.parent.postMessage(envelope, "*"),
+    subscribe: (deliver) => {
+      window.addEventListener("message", (event: MessageEvent) =>
+        deliver(event.data),
+      );
+    },
+  });
+
+  return {
+    send: channel.send,
+    onMessage: channel.onMessage,
+  };
+}

package/src/core/services/tab-channel.service.ts

@@ -0,0 +1,33 @@
+import type {
+  MessageChannel,
+  MessageListener,
+} from "./message-channel.service";
+
+/** A channel that only ever speaks for one tab, and only hears what is meant for it. */
+export type TabChannel = {
+  send: (type: string, payload?: object) => void;
+  onMessage: (type: string, listener: MessageListener) => () => void;
+};
+
+/**
+ * Binds a channel to one tab.
+ *
+ * Both ends carry every tab over one connection, so each message has to name the one it belongs to.
+ * Doing that at the call sites meant stamping an id on the way out and comparing it on the way in,
+ * in eight places across two engines, where a missed check shows up as one tab drawing another
+ * tab's DOM. Here it is in one place and a caller cannot get it wrong.
+ */
+export function createTabChannel(
+  channel: MessageChannel,
+  id: string,
+): TabChannel {
+  return {
+    send: (type, payload) => channel.send(type, { ...payload, id }),
+
+    onMessage: (type, listener) =>
+      channel.onMessage(type, (payload) => {
+        if ((payload as { id?: unknown } | undefined)?.id === id)
+          listener(payload);
+      }),
+  };
+}

package/src/device/components/tab-frame.component.tsx

@@ -0,0 +1,139 @@
+import {
+  createElement,
+  useEffect,
+  useReducer,
+  useState,
+  useTransition,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+
+/**
+ * The bar above every tab, and the tab's own component under it.
+ *
+ * Here rather than in each consumer's component: the name is one `registerTab` was already handed,
+ * and a way to draw the tab again is the same button every time.
+ *
+ * Drawing again is a `useReducer` in the app rather than a message from the panel. The component
+ * runs here, so re-rendering it is a local matter and what the render changes reaches the panel as
+ * ordinary ops. It is also the one thing no hook covers: state a component reads that React is not
+ * watching.
+ *
+ * Styled by class, with the rules in `renderer/renderer.css`, so the bar follows the panel's light
+ * and dark instead of carrying colours picked in the app.
+ */
+const DOCS = "https://axonpack.github.io/docs";
+const HOME = "https://axonpack.github.io";
+const REPO = "https://api.github.com/repos/axonpack/axonpack";
+
+/**
+ * How long a refresh waits before the tab is drawn again.
+ *
+ * Deliberate. Re-rendering takes a few milliseconds and the ops reach the panel in a few more, so
+ * the loader was up for less than a frame and the button read as doing nothing at all. This is long
+ * enough to see that it did.
+ */
+const RENDER_DELAY = 600;
+
+/**
+ * The star count, or null until it arrives and for good if it never does.
+ *
+ * The request is kept at module level rather than per component: every tab's bar draws this card, so
+ * an app with four tabs would otherwise ask GitHub four times for the same number, against a limit
+ * of sixty an hour for an unauthenticated caller. It runs in the app, which is where a `fetch` is,
+ * and only once a panel has asked for the tab, so an app nobody is debugging never makes it.
+ */
+let counted: Promise<number | null> | undefined;
+
+function useStars(): number | null {
+  const [stars, setStars] = useState<number | null>(null);
+
+  useEffect(() => {
+    counted ??= fetch(REPO)
+      .then((response) => response.json())
+      .then((repo: { stargazers_count?: number }) =>
+        typeof repo.stargazers_count === "number"
+          ? repo.stargazers_count
+          : null,
+      )
+      .catch(() => null);
+
+    void counted.then(setStars);
+  }, []);
+
+  return stars;
+}
+
+export function TabFrame({
+  name,
+  component,
+}: {
+  name: string;
+  component: ComponentType;
+}): ReactNode {
+  const [, refresh] = useReducer((n: number) => n + 1, 0);
+  const [isLoading, startTransition] = useTransition();
+  const stars = useStars();
+
+  const handleRefresh = () => {
+    startTransition(async () => {
+      await new Promise((resolve) => setTimeout(resolve, RENDER_DELAY));
+      refresh();
+    });
+  };
+
+  return (
+    <>
+      <header className="axonpack-tab-bar">
+        <span className="axonpack-tab-name">
+          {/* The mark is drawn by the class, for the same reason the refresh glyph is. */}
+          <span className="axonpack-tab-brand" tabIndex={0}>
+            <span className="axonpack-tab-about">
+              <b>{name}</b>
+              <span>
+                This tab is rendered via Axonpack React Native DevTools Tab.
+              </span>
+              <a
+                className="axonpack-tab-card"
+                href={HOME}
+                target="_blank"
+                rel="noreferrer"
+              >
+                <span className="axonpack-tab-card-mark" />
+                <b>Axonpack</b>
+                <span className="axonpack-tab-card-stars">
+                  {stars === null ? "" : `\u2605 ${stars}`}
+                </span>
+                <span className="axonpack-tab-card-slogan">
+                  Free, open source foundation libraries for React Native and
+                  Expo.
+                </span>
+              </a>
+              <span className="axonpack-tab-links">
+                <a href={DOCS} target="_blank" rel="noreferrer">
+                  Learn more
+                </a>
+              </span>
+            </span>
+          </span>
+          {name}
+        </span>
+        {/* Empty: the glyph is a mask in `renderer/renderer.css`, since SVG cannot cross. */}
+        <button
+          onClick={handleRefresh}
+          title="Render this tab again"
+          aria-label="Render this tab again"
+        />
+      </header>
+      <div className="axonpack-tab-body">
+        {isLoading ? (
+          <div className="axonpack-tab-loading">
+            <span className="axonpack-tab-loading-glyph" />
+          </div>
+        ) : (
+          createElement(component)
+        )}
+      </div>
+    </>
+  );
+}

package/src/device/react-reconciler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `@types/react-reconciler` tracks the old versions rather than this one, and the whole host config
+ * is passed as one object anyway. So the two calls this package makes are declared here, next to the
+ * only file that makes them, the same way `metro/node.d.ts` declares the Node APIs it uses.
+ */
+
+declare module "react-reconciler" {
+  import type { ReactNode } from "react";
+
+  export default function createReconciler(config: unknown): {
+    createContainer(
+      container: unknown,
+      tag: number,
+      hydrationCallbacks: unknown,
+      isStrictMode: boolean,
+      concurrentUpdatesByDefaultOverride: boolean | null,
+      identifierPrefix: string,
+      onUncaughtError: (error: unknown) => void,
+      onCaughtError: unknown,
+      onRecoverableError: unknown,
+    ): unknown;
+
+    updateContainer(
+      element: ReactNode,
+      container: unknown,
+      parentComponent: unknown,
+      callback: unknown,
+    ): void;
+  };
+}
+
+declare module "react-reconciler/constants" {
+  export const DefaultEventPriority: number;
+}