MobiDevTools Plugin Guide

Plugin API version 1 · MobiDevTools 4.1

MobiDevTools can be extended with new tabs. Every extra tab is a plugin, including the built-in Pharos (page audits), React, Vue, Angular and State tabs. Their source (plugins/*.js) is the reference implementation of everything described here.

There are two kinds of plugins:

Contents

1. Quick start — extension plugin
2. Quick start — page plugin
3. Plugin definition
4. Lifecycle
5. The api object
6. Working with page objects
7. UI, styling and theming
8. Mobile guidelines
9. Performance guidelines
10. Page plugins in depth
11. Security model
12. Packaging, ordering and distribution
13. Testing your plugin
14. Recipes
15. Compatibility and versioning

1. Quick start — extension plugin

Create plugins/hello.js:

"use strict";
(function () {
  if (!window.MDT_PLUGINS) return;

  window.MDT_PLUGINS.register({
    id: "hello",
    title: "Hello",
    icon: ["C12,12,9", "M8 14s1.5 2 4 2 4-2 4-2", "M9 9h.01", "M15 9h.01"],
    order: 100,
    mount(container, api) {
      const btn = api.ui.button("Count links", () => {
        const n = api.page.document.querySelectorAll("a").length;
        api.console.log("This page has", n, "links");
        api.toast(n + " links");
      });
      container.appendChild(btn);
    }
  });
})();

Add it to the injection list in background.js, before contentScript.js:

const MDT_MODULES = [
  "styles.js", "icons-data.js", "beautify.js", "assistant.js",
  "page-hooks.js", "inspector.js", "plugin-api.js",
  "plugins/react.js", "plugins/vue.js",
  "plugins/hello.js",          // ← your plugin
  "contentScript.js"
];

Load the extension as a temporary add-on (about:debugging → This Firefox → Load Temporary Add-on… → pick manifest.json), open any page, tap the MobiDevTools icon: there is a new Hello tab.

A complete, slightly bigger example is in examples/extension-plugin/perf-marks.js. It adds a "Marks" tab listing the page's performance.mark() / measure() entries.

2. Quick start — page plugin

Put this in your web app (development builds only, see §10):

const panel = {
  id: "flags",
  title: "Flags",
  render(container, mdt) {
    container.innerHTML = "<label><input type=checkbox id=dark> Dark mode</label>";
    container.querySelector("#dark").onchange = (e) => {
      document.body.classList.toggle("dark", e.target.checked);
      mdt.log("dark mode:", e.target.checked);
    };
  }
};
if (window.MobiDevTools) window.MobiDevTools.registerPanel(panel);
else (window.__MOBIDEVTOOLS_PLUGINS__ = window.__MOBIDEVTOOLS_PLUGINS__ || []).push(panel);

Open MobiDevTools on your page: there is a Flags tab. The last two lines cover both orders of events. If MobiDevTools is already open, the panel is registered right away. Otherwise it is queued and picked up when MobiDevTools starts.

A complete example (an app store inspector with an action log) is in examples/page-plugin/store-panel.html.

3. Plugin definition

MDT_PLUGINS.register(definition) validates and registers a tab. It throws a TypeError with a clear message on invalid input.

Icon encoding (same as the built-in tabs, see icons-data.js):

Icons are drawn with stroke="currentColor", stroke-width="2", no fill. Lucide/Feather icons work as-is.

Other registry functions:

MDT_PLUGINS.list()            // → array of registered definitions (sorted by order)
MDT_PLUGINS.get("react")      // → definition or null
MDT_PLUGINS.onRegister(fn)    // → unsubscribe function; fn(definition) for later registrations
MDT_PLUGINS.API_VERSION       // → 1

4. Lifecycle

register()  ──►  tab button appears
first tap   ──►  mount(container, api)  ──►  returns handle
every show  ──►  handle.onShow()
leave tab   ──►  handle.onHide()
navigation  ──►  handle.onNavigate(url)          (pushState/replaceState inside the same document)
element     ──►  handle.onElementSelected(node)  (the user selected a node in Elements)

The object returned by mount may implement any of these hooks:

mount(container, api) {
  let timer = null;
  return {
    onShow()             { refresh(); timer = setInterval(refresh, 2000); },
    onHide()             { clearInterval(timer); },
    onNavigate(url)      { refresh(); },
    onElementSelected(n) { /* n is the page node selected in Elements */ },
    dispose()            { clearInterval(timer); }
  };
}

A note on navigations: a full navigation or reload creates a new document. MobiDevTools is injected again into it, and your plugin with it. mount then runs on the new page, so you never need to clean up after a reload. onNavigate is only for single-page-app URL changes.

mount is lazy. Nothing of your plugin runs until the user opens its tab, so registering many plugins costs nothing at startup.

If mount or a hook throws, MobiDevTools catches it, shows the error in the console as [plugin <id>] …, and keeps working.

5. The api object

Every plugin receives its own api object.

5.1 Identity

5.2 api.ui — building the interface

All helpers return plain DOM elements that live inside MobiDevTools' shadow root. Build the rest with normal DOM APIs (createElement, textContent). Do not use innerHTML with page-controlled strings (see §11).

5.3 api.page — the inspected page

5.4 api.console

api.console.log/info/warn/error(...values) writes to the MobiDevTools console. Values are rendered with the inspector, so you can log live page objects.

api.console.list() returns a snapshot of the console: [{ type, text, source, url, restored, count, time }]. type is one of log info warn error debug result input. restored marks messages kept from the previous page by "Preserve log".

5.5 api.network

api.network.list() returns a snapshot of every request captured for the tab. These are the same objects described under the "network" event below. Use it for one-shot analyses. Use the "network" event to follow requests live.

5.6 api.sources

api.sources.open(url, line) opens a file in the Sources tab at a given line.

5.7 api.storage

A small persistent key–value store, private to your plugin (prefixed with plugin:<id>: in the extension storage). It is shared by all sites.

const n = await api.storage.get("runs", 0);
await api.storage.set("runs", n + 1);

Values must be JSON-serialisable.

5.8 api.on(event, handler) — events

Returns an unsubscribe function.

A request object (read-only):

{
  id, url, method, type,            // type: doc | script | css | img | font | media | xhr | ws | ping | other
  status, statusText, mime,
  reqHeaders: [{name, value}], resHeaders: [{name, value}],
  reqBody: { kind: "raw"|"form", data } | null,
  t0, tSend, tHeaders, tEnd, dur,   // epoch milliseconds
  size, fromCache, ip, error, pending,
  originUrl, documentUrl, thirdParty, hasBody
}

5.9 api.toast(message)

Shows a short message at the bottom of the panel.

6. Working with page objects

Firefox runs extension code in a sandbox that sees the page through Xray vision. With Xrays, DOM objects show only their standard properties, and objects created by page scripts look empty. MobiDevTools gives plugins the waived view, which sees everything the page sees:

const W = api.page.window;
W.myApp.store.getState();          // ✔ page-defined objects are fully visible
W.React && W.React.version;        // ✔
W.localStorage.getItem("token");   // ✔

Rules that keep you out of trouble:

1. Reading page values is safe. Property reads may run page getters, so treat them like any page code.
2. Calling page functions works: W.store.dispatch(action).
3. Creating values for the page: objects created in your plugin belong to the sandbox, and the page cannot always use them. Build page-side values with the page's constructors:

```js const action = new W.Object(); // a page object action.type = "reset"; W.store.dispatch(action);

W.store.dispatch(W.JSON.parse('{"type":"add","text":"hi"}')); // also fine `` 4. **Passing a callback to the page** (event listener,.then, subscription) needsexportFunction`:

js W.store.subscribe(exportFunction(() => refresh(), W)); 5. Wrap risky reads in try/catch: pages can contain proxies, revoked objects and throwing getters. The built-in plugins use a small helper:

js function safe(fn, dflt) { try { return fn(); } catch (e) { return dflt; } } 6. DOM nodes from page.document and from waived objects can be passed to page.highlight, page.reveal and ui.inspect as they are.

api.page.evaluate(code) is the simplest option when you just need the result of an expression in the page's own context:

const user = await api.page.evaluate("window.app && app.currentUser");

7. UI, styling and theming

Your tab is a flex column (display:flex; flex-direction:column). Give scrolling areas flex:1; overflow:auto; min-height:0, or use ui.split(), which already does this.

The panel lives in a closed shadow root, so page CSS never reaches your plugin and your CSS never reaches the page. Add CSS with api.ui.addStyle(css). Use a short prefix for your classes (.hello-…) so you don't clash with core classes.

Theme variables (always use them instead of hard-coded colours):

Reusable core classes: mdt-toolbar, mdt-chip (.on for active), mdt-tbinput, mdt-dsec (section header), mdt-drow + mdt-dk + mdt-dv (key/value rows), mdt-plugin-empty, mdt-plugin-badge.

api.ui.addStyle(`
  .hello-list { padding: 6px 10px; font-family: var(--mono); }
  .hello-item { color: var(--wht); border-bottom: 1px solid var(--bdr); padding: 4px 0; }
  .hello-item.bad { color: var(--red); }
`);

8. Mobile guidelines

Most MobiDevTools users run it on Firefox for Android.

• Use api.ui.onTap(el, fn) (or plain click) for row activation, never touchend. A touchend also fires at the end of a scroll gesture, which was a real bug in 3.x.
• Make interactive rows at least var(--touch-sm) tall.
• Prefer vertical layouts: ui.split() stacks automatically on phones.
• Inputs: use font-size ≥ 16px on mobile, otherwise Firefox zooms the page on focus. ui.input() and the core styles already handle this.
• Long-press is the mobile right-click. The core inspector uses ~550 ms.
• Keep toolbars short: they wrap on narrow screens.

9. Performance guidelines

• Do nothing in the registration code. Do the work in mount, and the periodic work only between onShow and onHide.
• Never poll faster than ~1 s. The built-in React/Vue tabs refresh every 1.2 s and re-render only when a structural signature changes.
• Cap what you render (the core console keeps ≤ 1000 rows in the DOM; the React tab caps at 4000 nodes). Render big lists lazily.
• Use ui.inspect() for values: it builds children only when a node is expanded.
• Clean up timers, observers and listeners in onHide / dispose.

10. Page plugins in depth

Registration

window.MobiDevTools.registerPanel({
  id: "store",                     // becomes the tab id "page-store"
  title: "Store",
  icon: ["R4,4,16,16,2"],          // optional
  render(container, mdt) { /* … */ }
});

• window.MobiDevTools exists only while MobiDevTools is injected in the page.
• Before that, push definitions to window.__MOBIDEVTOOLS_PLUGINS__ (an array). MobiDevTools reads it once at startup.
• render is called once, the first time the user opens the tab. After that the container is kept and shown or hidden as the user switches tabs.

The mdt object passed to render

The container

container is an ordinary <div> of your page, placed over the MobiDevTools panel area while your tab is active. It inherits nothing from the panel, so style it with your own CSS. It does inherit your page's global CSS, so scope your rules. Default colours: dark background #1e1e1e, text #d4d4d4.

Shipping only in development

Keep page plugins out of production bundles:

if (import.meta.env.DEV) import("./devtools/mobidevtools-panel.js");     // Vite
if (process.env.NODE_ENV !== "production") require("./mdt-panel");       // webpack

11. Security model

• Extension plugins run in the content-script sandbox, with the same privileges as MobiDevTools' panel code. They are reviewed together with the extension when it is published on addons.mozilla.org. Rules:
• No remote code: no eval, new Function, <script src="https://…"> or code downloaded at runtime. Code you run in the page through api.page.evaluate() must come from the user or from your plugin's own source.
• Build UI with textContent/createElement. Never put page-controlled strings into innerHTML.
• Don't send page data anywhere. MobiDevTools declares data_collection_permissions: none.
• Page plugins run as the page and get nothing more than the page already has:
• They receive a container in the light DOM, outside MobiDevTools' closed shadow root. A page plugin cannot use its container (getRootNode(), parentNode…) to read the panel. That matters because the Network tab can display HttpOnly cookies and authorization headers that page scripts must never see.
• mdt.log() only displays values. It gives no access to extension APIs.
• MobiDevTools' own UI is never handed to page code, and events inside the panel do not propagate to the page.

12. Packaging, ordering and distribution

• Extension plugins are files of the extension. Add them to MDT_MODULES in background.js after plugin-api.js and before contentScript.js. Order among plugins does not matter: tab order comes from order.
• To share a plugin with the community, open a pull request / patch with the file and the MDT_MODULES line. Attach a screenshot and a test page.
• Firefox only installs signed extensions. A fork with extra plugins must be signed through addons.mozilla.org (it can be "unlisted" for private use), or loaded as a temporary add-on for development.

13. Testing your plugin

• Desktop: about:debugging → Load Temporary Add-on. Edit, then press Reload. Content-script errors appear in the Browser Console (Ctrl+Shift+J).
• Android: use web-ext run -t firefox-android (needs adb) or install a signed build.
• Plugin errors are also shown inside the MobiDevTools console as [plugin <id>] ….
• The source package includes a test harness (test/, Node + Firefox WebDriver BiDi) used to verify every release. The React and Vue suites are good templates for plugin tests.

14. Recipes

List the selected element's dataset

mount(container, api) {
  const box = api.ui.el("div");
  container.appendChild(box);
  function show(node) {
    box.textContent = "";
    if (!node) { box.appendChild(api.ui.empty("Select an element in Elements")); return; }
    box.appendChild(api.ui.inspect(api.page.unwrap(node).dataset, { expanded: true }));
  }
  show(api.page.selectedElement);
  return { onElementSelected: show };
}

Watch failing requests

mount(container, api) {
  const list = api.ui.el("div");
  container.appendChild(list);
  api.on("network", (reqs) => reqs
    .filter((r) => !r.pending && (r.error || r.status >= 400))
    .forEach((r) => list.appendChild(api.ui.el("div", "mdt-drow", r.status + " " + r.method + " " + r.url))));
}

Let the user pick an element, then audit it

api.ui.button("Pick", async () => {
  const node = await api.page.pick();
  if (!node) return;
  const cs = api.page.window.getComputedStyle(node);
  api.console.log("contrast check for", node, cs.color, "on", cs.backgroundColor);
});

Talk to a framework devtools hook

const hook = api.page.window.__MY_FRAMEWORK_DEVTOOLS__;
if (hook) hook.on("update", exportFunction(() => refresh(), api.page.window));

15. Compatibility and versioning

• api.apiVersion is 1 for the whole 4.x series. Additions are backwards compatible: new optional fields, events and helpers.
• A breaking change would bump apiVersion. Check it if you depend on something specific:

js if (api.apiVersion < 1) { container.appendChild(api.ui.empty("Needs MobiDevTools 4+")); return; } * Internal functions that are not on api (anything else you can reach on window.MDT_*) are not part of the API and may change in any release.

MobiDevTools — © 2025–2026 Francesco De Stefano — MIT License.