LocatorJS Source Code Analysis: Architecture, Chrome Extension Integration, and Runtime Mechanics

Introduction

The author discovered LocatorJS, a tool that lets developers locate source code directly from the browser UI for frameworks such as React, Preact, Solid, Vue, and Svelte. Curious about its inner workings, they cloned the repository and began a systematic source‑code exploration.

Preparation

1. Clone the source : After pulling the code, the project structure shows an apps folder containing the Chrome extension and examples, and a packages folder with shared modules like babel-jsx , locatorjs , and runtime . The monorepo is managed with Lerna, so dependencies are installed via lerna bootstrap .

2. Start the project : Once dependencies are ready, run yarn dev . Turbo builds the project quickly, and the development server starts on a dynamic port (e.g., 3348) which can be opened in a browser.

3. Load the Chrome extension : Install the React DevTools extension and load the development version of the LocatorJS Chrome extension from apps/extension/build/development_chrome via Chrome's extension management page.

Source Code Analysis

Chrome Extension

The entry point is apps/extension/src/pages/Content/index.ts , which injects hook.bundle.js into the page and sets document.documentElement.dataset.locatorClientUrl to point to client.bundle.js . The extension also contains Background (currently empty) and Popup code.

The Hook bundle ensures that React DevTools is installed and then injects the runtime script. It listens for DOMContentLoaded and inserts the script referenced by locatorClientUrl , handling iframe scenarios as well.

The ClientUI simply re‑exports @locator/runtime , which contains the core logic.

Runtime Package

In packages/runtime/src/index.ts the two integration methods (Chrome extension or direct @locator/runtime import) both call initRuntime with different parameters.

initRuntime.ts creates a Shadow DOM container to isolate CSS and then mounts the Runtime component, taking SSR into account (the article focuses on client‑side rendering).

The Runtime component ( packages/runtime/src/components/Runtime.tsx ) is built with SolidJS. It registers listeners for mouseover , keydown , keyup , click , and scroll events.

When the mouse hovers over an element while the Option key is held, a red outline ( MaybeOutline ) appears. The outline component gathers element information via getElementInfo , which uses an adapter pattern to handle different frameworks.

For React, reactAdapter.ts leverages the internal Fiber tree. The key function findFiberByHtmlElement (implemented in findFiberByHtmlElement.ts ) locates the Fiber node associated with a DOM element. The Fiber’s _debugSource field already contains the source file, line, and column, thanks to the Babel plugin @babel/plugin-transform-react-jsx-source .

The plugin adds a __source prop to JSX elements, which later becomes _debugSource on the Fiber. This enables the click handler to open a vscode:// URL that jumps directly to the source location in VS Code.

The visual red box around the element is rendered by ComponentOutline.tsx , which computes the bounding box via getBoundingClientRect on the Fiber’s host instance.

Summary

By dissecting LocatorJS, the reader learns how to develop Chrome extensions, use SolidJS for UI, apply Shadow DOM for style isolation, implement the adapter pattern, and understand React Fiber internals. The article focuses on the React‑DevTools integration path; an alternative data‑id approach is mentioned but not explored.

References

Chrome Extensions content scripts – Chrome Developers (https://developer.chrome.com/docs/extensions/mv3/content_scripts/) LocatorJS official site (https://www.locatorjs.com/)