Technical Analysis of San DevTools – Architecture, Core Concepts, and Remote Debugging

In this article we introduce the first part of the "San DevTools Technical Analysis" series, focusing on the main functions, overall architecture, and key module concepts of San DevTools.

Feature Overview

San DevTools can be used in two ways:

Install the Chrome extension from the Chrome Web Store (see the usage documentation).

Install the standalone version via npm, which enhances remote‑debugging capabilities and is the recommended approach for most scenarios.

The standalone version supports two debugging modes, demonstrated in the accompanying video:

Remote debugging mode for San applications.

General Chrome remote‑debugging mode that works with mobile H5, IE, Safari, etc.

Core Concepts

San DevTools is a debugging tool designed for San applications. To help readers understand the concepts, we first ask:

How would you design and implement a remote‑debugging tool that can view a component tree?

We identify four core modules:

Frontend : The debugging UI, built on Chrome DevTools panels (Elements, Console, Network, Source) and extended with San‑specific panels such as Component, History, Store, Event, and Message.

Backend : The injected script running inside the target page, acting as the counterpart of the frontend.

Protocol : The Remote Debugging Protocol that defines JSON‑based methods and events for communication between Frontend and Backend.

Message Channel : The transport layer (WebSocket, Chrome Runtime, Chrome Extension channels) that carries messages between the two sides.

Additional supporting modules are:

Bridge : An instance that simplifies event sending between Frontend and Backend.

Hook : Injected hooks that monitor the target page’s JavaScript/DOM and emit lifecycle events.

Agent : Processes data collected by Hook or received via Bridge, performing tasks such as component‑tree generation.

Architecture & Flow

The overall architecture diagram (see image) shows how the components interact. The initialization stage includes:

Chrome extension entry defined in manifest.json.

Standalone version starts a Node server that serves JavaScript files and injects them into the target page.

The Hook injects a global variable __san_devtool__ to expose San‑related information.

Connection establishment involves a two‑handshake protocol, creation of two Bridge instances, and the use of either WebSocket or Chrome Runtime long‑living connections.

Code Example – Server Side Bridge

import WebSocket from 'ws';

const wss = new WebSocket.Server({port: 8080});

wss.on('connection', ws => {
    const bridge = new Bridge({
        listen(fn) { ws.on('message', fn); },
        send(data) { ws.send(data); }
    });
});

io.listen(8080);

Code Example – Backend/Frontend Bridge

const wss = new WebSocket('wss://localhost:8080');

const bridge = new Bridge({
    listen(fn) { wss.onmessage = fn; },
    send(data) { wss.send(data); }
});

During the initialization phase, the system decides whether to use Chrome extension or the standalone mode, injects the Hook, and establishes the Bridge and Protocol.

Other Stages

In later stages, such as component‑information synchronization and component‑tree rendering, the following steps occur:

San loads the development version (san.dev.js) to enable debugging.

The injected global variable sends lifecycle data to the DevTools.

The Backend records component attach events and generates the component tree.

Finally, the article summarizes the four core modules and three auxiliary concepts, and hints at the next article, which will dive deeper into the Message Channel and Debugging Protocol.