Building Expo DevTools Plugins with CLI Interfaces

Build CLI tools that communicate with running Expo apps via the DevTools plugin system.

Architecture Overview

┌─────────────────┐     WebSocket      ┌─────────────────┐
│   CLI Client    │◄──────────────────►│  Expo Dev Server │
│  (Bun + Stricli)│                    │   (Metro)        │
└─────────────────┘                    └────────┬────────┘
                                                │
                                       ┌────────▼────────┐
                                       │   React Native  │
                                       │   App + Hook    │
                                       └─────────────────┘

Preferred Tech Stack

useDevToolsPluginClient

Project Structure

cli/
├── index.ts              # Entry point with shebang
├── app.ts                # Stricli app definition with routes
├── client.ts             # WebSocket client for devtools
├── types.ts              # Shared TypeScript types
├── formatters.ts         # Output formatting (table, JSON)
└── commands/
    ├── query.ts          # Read commands
    ├── write.ts          # Write commands
    └── status.ts         # Status/health commands

src/devtools/
└── useMyPluginDevTools.ts  # App-side message handler hook

Step 1: Configure the Module

Add devtools config to

expo-module.config.json

{
  "name": "MyModule",
  "platforms": ["ios", "android"],
  "devtools": {
    "name": "My Plugin",
    "id": "my-plugin"
  }
}

Step 2: Create the App-Side Hook

// src/devtools/useMyPluginDevTools.ts
import { useEffect } from "react";
import { useDevToolsPluginClient } from "expo/devtools";

interface PluginMessage {
  id: string;
  type: string;
  payload: Record<string, unknown>;
}

export function useMyPluginDevTools() {
  const client = useDevToolsPluginClient("my-plugin"); // Must match devtools.id

  useEffect(() => {
    if (!client) return;

    const handleMessage = (data: PluginMessage) => {
      const { id, type, payload } = data;

      const sendResult = (result: unknown) => {
        client.sendMessage("result", { id, type: "result", data: result });
      };

      const sendError = (error: Error) => {
        client.sendMessage("error", {
          id,
          type: "error",
          error: error.message,
        });
      };

      (async () => {
        try {
          switch (type) {
            case "getData":
              const data = await fetchData(payload.query as string);
              sendResult(data);
              break;
            default:
              sendError(new Error(`Unknown message type: ${type}`));
          }
        } catch (error) {
          sendError(error as Error);
        }
      })();
    };

    const subscription = client.addMessageListener(
      "message",
      (msg: unknown) => {
        handleMessage(msg as PluginMessage);
      }
    );

    return () => {
      subscription?.remove?.();
    };
  }, [client]);
}

Step 3: Create the CLI Client

// cli/client.ts
const DEFAULT_PORT = 8081;
const REQUEST_TIMEOUT = 30000;
const PROTOCOL_VERSION = 1;

export class PluginClient {
  private ws: WebSocket | null = null;
  private pending = new Map<string, { resolve: Function; reject: Function }>();
  private connected = false;
  private browserClientId = Date.now().toString();
  private pluginName = "my-plugin"; // Must match devtools.id

  async connect(port = DEFAULT_PORT): Promise<void> {
    if (this.connected) return;

    return new Promise((resolve, reject) => {
      // IMPORTANT: Use the broadcast endpoint
      const url = `ws://localhost:${port}/expo-dev-plugins/broadcast`;
      this.ws = new WebSocket(url);

      const timeout = setTimeout(() => {
        reject(new Error(`Connection timeout to ${url}`));
      }, 10000);

      this.ws.addEventListener("open", () => {
        clearTimeout(timeout);
        this.connected = true;
        this.sendHandshake();
        resolve();
      });

      this.ws.addEventListener("error", () => {
        clearTimeout(timeout);
        reject(new Error(`Failed to connect to Expo devtools at ${url}`));
      });

      this.ws.addEventListener("close", () => {
        this.connected = false;
      });

      this.ws.addEventListener("message", (event) => {
        this.handleMessage(event.data);
      });
    });
  }

  private sendHandshake(): void {
    // CRITICAL: Must include all these fields
    const handshake = {
      protocolVersion: PROTOCOL_VERSION, // Must be 1
      pluginName: this.pluginName,
      method: "handshake",
      browserClientId: this.browserClientId,
      __isHandshakeMessages: true, // Required flag
    };
    this.ws?.send(JSON.stringify(handshake));
  }

  private handleMessage(data: string | ArrayBuffer): void {
    if (typeof data === "string") {
      try {
        const parsed = JSON.parse(data);
        if (parsed.__isHandshakeMessages) return; // Ignore handshake acks
        if (parsed.messageKey) {
          this.handlePackedMessage(parsed);
        }
      } catch {
        // Not JSON, ignore
      }
    }
  }

  private handlePackedMessage(msg: { messageKey: any; payload: any }): void {
    const { messageKey, payload } = msg;
    if (messageKey.pluginName !== this.pluginName) return;

    if (messageKey.method === "result" || messageKey.method === "error") {
      const response = payload as {
        id: string;
        data?: unknown;
        error?: string;
      };
      const pending = this.pending.get(response.id);
      if (!pending) return;

      this.pending.delete(response.id);
      if (messageKey.method === "error" || response.error) {
        pending.reject(new Error(response.error ?? "Unknown error"));
      } else {
        pending.resolve(response.data);
      }
    }
  }

  async send<T>(type: string, payload: unknown): Promise<T> {
    if (!this.ws || !this.connected) {
      throw new Error("Not connected to Expo devtools");
    }

    const id = crypto.randomUUID();
    return new Promise((resolve, reject) => {
      this.pending.set(id, { resolve, reject });

      // CRITICAL: Send as JSON string, NOT binary ArrayBuffer
      const msg = {
        messageKey: { pluginName: this.pluginName, method: "message" },
        payload: { id, type, payload },
      };
      this.ws!.send(JSON.stringify(msg));

      setTimeout(() => {
        if (this.pending.has(id)) {
          this.pending.delete(id);
          reject(new Error("Request timeout"));
        }
      }, REQUEST_TIMEOUT);
    });
  }

  async disconnect(): Promise<void> {
    this.ws?.close();
    this.ws = null;
    this.connected = false;
  }
}

Step 4: Create the CLI Entry Point

// cli/index.ts
#!/usr/bin/env bun
import { run } from "@stricli/core";
import { app } from "./app";

await run(app, process.argv.slice(2), { process });

// cli/app.ts
import { buildApplication, buildRouteMap } from "@stricli/core";

const routes = buildRouteMap({
  routes: {
    status: () => import("./commands/status").then((m) => m.default),
    query: () => import("./commands/query").then((m) => m.default),
  },
});

export const app = buildApplication(routes, {
  name: "my-cli",
  versionInfo: { currentVersion: "1.0.0" },
});

Step 5: Configure package.json

{
  "bin": {
    "my-cli": "cli/index.ts"
  },
  "scripts": {
    "cli": "bun cli/index.ts"
  },
  "dependencies": {
    "@stricli/core": "^1.1.0"
  }
}

Footguns and Solutions

1. Binary vs JSON Messages

Problem: Messages sent as

ArrayBuffer

// WRONG - Will not work
const encoder = new TextEncoder();
this.ws.send(encoder.encode(JSON.stringify(msg)).buffer);

// CORRECT - Send as JSON string
this.ws.send(JSON.stringify(msg));

Debugging: Use

websocat

websocat -v ws://localhost:8081/expo-dev-plugins/broadcast

2. Wrong WebSocket Endpoint

Problem: Using

/message

// WRONG
const url = `ws://localhost:${port}/message`;

// CORRECT - Must use broadcast endpoint
const url = `ws://localhost:${port}/expo-dev-plugins/broadcast`;

Debugging: Use curl to verify WebSocket upgrade:

curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: test" -H "Sec-WebSocket-Version: 13" \
  http://localhost:8081/expo-dev-plugins/broadcast

3. Missing Handshake Fields

Problem: Connection appears to work but messages aren't routed.

// WRONG - Missing required fields
const handshake = { pluginName: "my-plugin" };

// CORRECT - All fields required
const handshake = {
  protocolVersion: 1, // Must be 1
  pluginName: "my-plugin",
  method: "handshake",
  browserClientId: "unique-id",
  __isHandshakeMessages: true, // Critical flag
};

4. Protocol Version Mismatch

Problem:

terminateBrowserClient

// WRONG
protocolVersion: 2;

// CORRECT - Use version 1
protocolVersion: 1;

5. Plugin Name Mismatch

Problem: Messages sent but never received by app.

The

pluginName

• expo-module.config.json

  →

  devtools.id

• App hook →

  useDevToolsPluginClient("my-plugin")

• CLI client →

  this.pluginName = "my-plugin"

6. Hook Not Setting Up Listener

Problem: Hook logs "connected" but messages timeout.

Check that

useDevToolsPluginClient

// CORRECT
import { useDevToolsPluginClient } from "expo/devtools";

// WRONG - different package
import { useDevToolsPluginClient } from "@expo/devtools-plugin-client";

7. Message Listener Method Name

Problem: App receives connection but not messages.

The

addMessageListener

messageKey.method

// CLI sends with method: "message"
const msg = {
  messageKey: { pluginName: "my-plugin", method: "message" },
  payload: { id, type, payload },
};

// App listens for "message"
client.addMessageListener("message", handler);

Debugging Techniques

1. Monitor WebSocket Traffic

# Listen to all broadcasts
websocat --no-close -v ws://localhost:8081/expo-dev-plugins/broadcast

# Send test handshake
echo '{"protocolVersion":1,"pluginName":"my-plugin","method":"handshake","browserClientId":"test","__isHandshakeMessages":true}' | \
  websocat ws://localhost:8081/expo-dev-plugins/broadcast

2. Check App Console Logs

bunx xcobra expo console --json | grep -i "my-plugin\|devtools"

3. Verify Hook is Running

Add temporary logging to the hook:

useEffect(() => {
  console.log("[DevTools] client:", client ? "connected" : "null");
  if (!client) return;
  console.log("[DevTools] Setting up listener");
  // ...
}, [client]);

4. Test Connection Independently

// Minimal test script
const ws = new WebSocket("ws://localhost:8081/expo-dev-plugins/broadcast");
ws.onopen = () => {
  console.log("Connected");
  ws.send(
    JSON.stringify({
      protocolVersion: 1,
      pluginName: "my-plugin",
      method: "handshake",
      browserClientId: "test",
      __isHandshakeMessages: true,
    })
  );
};
ws.onmessage = (e) => console.log("Received:", e.data);

Testing Workflow

1. Start the app:

   yarn expo run:ios

   or have simulator running with Expo Go
2. Verify Metro is running: Check

   http://localhost:8081

   responds
3. Test CLI connection:

   bun cli/index.ts status

4. Check for errors: Monitor both CLI output and app console

Reference Implementation

See the HealthKit CLI in this repo:

• cli/

  - Full CLI implementation

• src/dev-tools/useHealthKitDevTools.ts

  - App-side hook

• example/App.tsx

  - Hook usage in app