Inside PageSpy: How Huolala’s Open‑Source Front‑End Debugger Works

Huolala’s open‑source front‑end remote debugging tool PageSpy has gained over 3000 stars on GitHub. To meet diverse debugging scenarios, a mini‑program debugging capability is under internal testing.

Three Repositories

PageSpy consists of three repositories:

Web UI code: HuolalaTech/page-spy-web Server API code: HuolalaTech/page-spy-api Client SDK code:

HuolalaTech/page-spy

Repository Functions

What the SDK does

Common development actions such as console logging, network requests, and cache updates are intercepted by the SDK and displayed in a console‑style UI on the debugging side.

// output log
console.log(res.data.users);

// send request
fetch('https://example.com/todos');

// update cache
localStorage.setItem('foo', 'foo');

For example, when console.log(res.data.users) is called, the SDK wraps the native method via a plugin system.

abstract class PageSpyPlugin {
  public constructor(public name: string) {}
  public abstract onCreated?(): void;
  public abstract onLoaded?(): void;
}
class ConsolePlugin implements PageSpyPlugin {
  public async onCreated() {
    const type: SpyConsole.ProxyType[] = ['log','info','error','warn'];
    type.forEach(item => {
      this.console[item] = window.console[item];
      window.console[item] = (...args:any[]) => {
        // ...
      };
    });
  }
}

The SDK currently includes the following plugins: plugins/console: wraps console methods. plugins/network: wraps fetch, XMLHttpRequest, navigator.sendBeacon. plugins/system: checks ES5+ API compatibility. plugins/database: handles IndexedDB. plugins/storage: wraps localStorage, sessionStorage, cookie. plugins/error: handles onerror, unhandledrejection. plugins/page: captures page structure via document.documentElement.outerHTML.

Event debugging (e.g., pushing cached data when the debugging client connects, executing code from the debugging console, refreshing the page view, paging through IndexedDB data) is not implemented as a plugin because it depends heavily on a Socket instance and each plugin handles its own events.

SDK Context Awareness

After deploying PageSpy, the SDK is loaded via a script tag, for example:

<script crossorigin="anonymous" src="https://example.com/page-spy/index.min.js"></script>

Instantiating the client is as simple as:

<script>
  window.$pageSpy = new PageSpy();
</script>

The SDK automatically resolves the server API and client origin from the script URL, e.g., https://example.com/page-spy/index.min.js, producing a configuration with host, origin, project, autoRender, and title.

const scriptLink = (document.currentScript as HTMLScriptElement)?.src;
const resolveConfig = () => {
  if (!scriptLink) return null;
  const { host, origin } = new URL(scriptLink);
  return {
    api: host,
    clientOrigin: origin,
    project: 'default',
    autoRender: true,
    title: '',
  };
};

Server Responsibilities

The server provides REST endpoints for room creation, room listing, and WebSocket joining, and it automatically destroys inactive rooms and routes messages appropriately. /api/v1/room/create – create a debugging room. /api/v1/room/list – list rooms for the debugging client. /api/v1/ws/room/join – establish WebSocket connections.

Debugging Client Role

The debugging client consumes the information supplied by the SDK and presents an interactive UI for developers throughout their debugging workflow.

Interaction Diagram

Data Security

Huolala commits to transparency and private deployment: the source code is fully open on GitHub, and when self‑hosted, all collected data stays on the user’s own server.

For questions, contact the project via the GitHub issues page.