Mobile DevTools

Next-Gen Framework-Agnostic In-App Mobile Debugger & Inspector Overlay for Web Applications

📌 Table of Contents

📚 Comprehensive Documentation Suite
📸 Showcase
💡 Motivation & Why Use It?
✨ Core Capabilities
🏗️ Technical Architecture
🚀 Framework Quickstart
⚙️ Full Configuration & Props Reference
🎨 Theme Engine & Customization
📂 Monorepo Structure
🛠️ Development Setup
📄 License

📸 Showcase

💡 Motivation & Why Use It?

Debugging mobile web applications or QA staging builds on physical smartphones, tablets, or embedded webviews is historically painful:

❌ Requiring physical USB debugging cables connected to a desktop computer.
❌ Configuring Safari Remote Inspector or Chrome Inspect ports over local WiFi.
❌ Losing console logs when a mobile browser crashes or refreshes.
❌ Inability to inspect network traffic on production staging environments without desktop proxies (Charles / Fiddler / Proxyman).

mobile-devtools eliminates these pain points entirely. It embeds a lightweight, high-performance floating badge and overlay drawer directly inside your web application. You can inspect logs, monitor network calls, browse DOM trees, edit local storage, and inspect device specs anytime, anywhere — directly on screen without external tools or cables.

✨ Core Capabilities

⚡ Ultra-Lightweight & Fast: Small footprint (~32.2 kB gzipped / ~135.9 kB minified) with zero runtime dependencies, ensuring zero impact on page load speed or mobile frame rates.
🌳 DOM Elements Inspector (Elements Tab): Real-time HTML DOM tree browser, node expansion, interactive element picker, box model visualization (margin, border, padding, content), computed CSS styles, and grouped style categories (Layout, Flexbox, Grid, Typography, Colors).
🚀 Quick Bug Exporter: Instant 1-click bug report sharing via Web Share API (navigator.share) to WhatsApp, Telegram, Slack, AirDrop, or Email with text file download and copy fallbacks.
🌐 Network Throttling Simulator: Simulate Slow 3G, Fast 3G, or Offline connection modes directly on mobile devices with synthetic latency injection.
⚡ Cable-Free Mobile Inspection: Debug directly on physical iOS / Android devices, mobile webviews, or mobile Safari/Chrome.
🛡️ Shadow DOM Style Isolation: Rendered inside a Shadow DOM container (<mobile-devtools-root>), guaranteeing zero CSS leaks into your app's global styles and zero style pollution from Tailwind, Bootstrap, or global CSS resets.
📋 Console Tab: Real-time capture of console.log, info, warn, error, and debug with live search, log sorting (Newest, Oldest, Errors, Frequent), JSON tree preview, and unread error badges.
🌐 Network Tab: Live interception of fetch, XMLHttpRequest (XHR), native WebSocket connections, and EventSource (SSE) with HTTP status indicators, latency timing, request/response headers, JSON body previews, WebSocket SVG direction frames, and unified sort & status class filtering (Newest, Oldest, Slowest, Fastest, 2xx Success, 3xx Redirect, 4xx Client Error, 5xx Server Error, 1xx Info, Network Error).
💾 Storage Tab: Real-time inspector and editor for localStorage, sessionStorage, document.cookie, and indexedDB databases and object stores.
💻 System Info Tab: Real-time diagnostic monitor for viewport dimensions, device pixel ratio (DPR), user agent string, memory limit, and screen orientation.
🔌 Pluggable Custom Tabs (customTabs): Easily extend DevTools by adding custom tabs with your own DOM rendering callbacks (render(container)).
🎨 Granular UI Style Overrides (styles): Fine-grained inline CSS style overrides for badge, drawer, overlay, and handle (styles={{ badge: {}, drawer: {}, overlay: {} }}).
🎨 Dynamic Theme Engine: Built-in Light Mode and Dark Mode with auto-contrast luminance detection, accent color swatches, and custom background palettes.
🧪 Comprehensive Test Suite: Tested with 111 Unit Tests (100% Passed) + 21 Playwright E2E Tests (100% Passed) across Desktop Chrome, Mobile Chrome, and Mobile Safari.
🧩 Framework Agnostic: Native support for React 18/19, Vue 3, Svelte 4/5, and Vanilla JS.

🏗️ Technical Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                                 mobile-devtools                                 │
└────────────────────────────────────────┬────────────────────────────────────────┘
                                         │
        ┌───────────────────┬────────────┴───────────┬───────────────────┐
        ▼                   ▼                        ▼                   ▼
   Vanilla JS             React                    Vue 3              Svelte
(mobile-devtools) (mobile-devtools/react)  (mobile-devtools/vue) (mobile-devtools/svelte)
        │                   │                        │                   │
        └───────────────────┴────────────┬───────────┴───────────────────┘
                                         │
                           ┌─────────────▼─────────────┐
                           │   Native Shadow DOM Host  │
                           │   <mobile-devtools-root>  │
                           └─────────────┬─────────────┘
                                         │
            ┌────────────────────────────┴──────────────────┐
            │                                               │
┌───────────▼─────────────────┐   ┌─────────────────────────▼──────────────┐
│      Core Interceptors      │   │               UI Engine                │
├─────────────────────────────┤   ├────────────────────────────────────────┤
│ • Console Interceptor       │   │ • Floating Badge View (floating-badge) │
│ • Fetch / XHR Interceptor   │   │ • Drawer Views & Tabs (drawer)         │
│ • DOM Elements Inspector    │   │ • Pluggable Custom Tabs (customTabs)   │
│ • Storage Inspector         │   │ • Auto Contrast Theme Helper           │
│ • DevTools Store & State    │   │ • Bug Exporter Engine                  │
└─────────────────────────────┘   └────────────────────────────────────────┘

🚀 Framework Quickstart

📦 Installation

npm install mobile-devtools
# or
pnpm add mobile-devtools

⚛️ React Integration

Import from mobile-devtools/react:

import React from 'react';
import { MobileDevTools } from 'mobile-devtools/react';

export default function App() {
  return (
    <>
      <YourAppRoutes />

      {/* Mobile DevTools Overlay */}
      <MobileDevTools
        title="My App Debugger"
        position="bottom-right"
        enabledTabs={['console', 'elements', 'network', 'storage', 'system']}
        theme={{ mode: 'dark', accentColor: '#0070f3' }}
        styles=".devtools-badge { opacity: 0.9; }"
        renderBadge={(container, { unreadErrors }) => {
          container.innerHTML = `<span style="color:#fff;">🐞 My Debugger ${unreadErrors ? `(${unreadErrors})` : ''}</span>`;
        }}
        customTabs={[
          {
            id: 'analytics',
            title: 'Analytics',
            render: (container) => {
              container.innerHTML =
                '<div style="padding:16px;color:#fff;">📊 Custom Event Log</div>';
            },
          },
        ]}
      />
    </>
  );
}

💚 Vue 3 Integration

Import from mobile-devtools/vue:

<script setup>
  import { MobileDevTools } from 'mobile-devtools/vue';

  const customTabs = [
    {
      id: 'analytics',
      title: 'Analytics',
      render: (container) => {
        container.innerHTML = '<div style="padding:16px;color:#fff;">📊 Custom Event Log</div>';
      },
    },
  ];
</script>

<template>
  <YourAppLayout />
  <MobileDevTools
    title="My App Debugger"
    position="bottom-right"
    :enabled-tabs="['console', 'elements', 'network', 'storage', 'system']"
    :theme="{ mode: 'dark', accentColor: '#0070f3' }"
    :custom-tabs="customTabs"
  />
</template>

🔥 Svelte Integration

Import from mobile-devtools/svelte:

<script>
  import { mobileDevTools } from 'mobile-devtools/svelte';
</script>

<div use:mobileDevTools={{
  title: 'My App Debugger',
  position: 'bottom-right',
  shakeToToggle: true,
  theme: { mode: 'dark' }
}}>
  <YourAppLayout />
</div>

🧡 Svelte 4/5 Integration

Import from mobile-devtools/svelte:

<script>
  import { useMobileDevTools } from 'mobile-devtools/svelte';
</script>

<div use:useMobileDevTools={{
  title: 'My App Debugger',
  position: 'bottom-right',
  theme: { mode: 'dark', accentColor: '#0070f3' }
}}>
  <YourAppLayout />
</div>

🍦 Vanilla JS / Legacy Apps

Option A: npm Package Import

import { createMobileDevTools } from 'mobile-devtools';

// Instantiate DevTools overlay
const devtools = createMobileDevTools({
  title: 'My App Debugger',
  position: 'bottom-right',
  enabledTabs: ['console', 'elements', 'network', 'storage', 'system'],
  theme: {
    mode: 'dark',
    accentColor: '#0070f3',
  },
  styles: `.devtools-badge { opacity: 0.9; } .devtools-drawer { max-height: 85vh; }`,
  customTabs: [
    {
      id: 'analytics',
      title: 'Analytics',
      render: (container) => {
        container.innerHTML = '<div style="padding:16px;color:#fff;">📊 Custom Event Log</div>';
      },
    },
  ],
});

Option B: Direct CDN / UNPKG Script Tag (Zero Build Step)

<script type="module">
  import { createMobileDevTools } from 'https://unpkg.com/mobile-devtools';

  // Works out-of-the-box in any static HTML page or legacy app
  createMobileDevTools({
    title: 'My App Debugger',
    position: 'bottom-right',
    theme: { mode: 'dark' },
  });
</script>

⚙️ Full Configuration & Props Reference

Below is the complete reference table for all configuration options supported by <MobileDevTools /> / createMobileDevTools():

Option / Prop	Type	Default	Description
`enabled`	`boolean`	`true` (in dev)	Enable or disable the DevTools overlay. Automatically set to `false` in production builds.
`forceEnable`	`boolean`	`false`	Force enable DevTools overlay in production builds for QA testing & staging previews.
`showBadge`	`boolean`	`true`	Show or hide the floating trigger badge on screen.
`renderBadge`	`(container, props) => void`	`undefined`	Custom render callback function to craft inner floating badge DOM structure while retaining drag & drop gesture handling.
`defaultOpen`	`boolean`	`false`	Set to `true` to open drawer automatically on initial page mount.
`shakeToToggle`	`boolean \| ShakeToToggleConfig`	`true`	Enable physical device shake gesture (`shakeToToggle={true}`) or customize options (`shakeToToggle={{ enabled: true, threshold: 15 }}`).
`title`	`string`	`'DevTools'`	Label shown on floating badge and drawer header.
`icon`	`any`	`undefined`	Custom icon (Emoji string like `'⚡'`, SVG markup string, Image URL, or Base64 data URI).
`position`	`BadgePositionPreset \| BadgePosition`	`'bottom-right'`	Initial corner/edge preset (`'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'`, `'bottom'`, `'top'`, `'left'`, `'right'`) or `{ x, y }` object.
`initialTab`	`DevToolsTabId`	`'console'`	Default active tab when drawer opens (`'console'`, `'elements'`, `'network'`, `'storage'`, `'system'`).
`enabledTabs`	`DevToolsTabId[]`	`['console', 'elements', 'network', 'storage', 'system']`	Filter which built-in tabs are enabled in drawer.
`customTabs`	`CustomTabDefinition[]`	`[]`	Pluggable consumer tabs array with custom DOM rendering callbacks (`render(container)`).
`autoSnapBadge`	`boolean`	`false`	Enable magnetic snapping of badge to nearest screen edge on drag release.
`styles`	`string`	`undefined`	Custom raw CSS string injected into DevTools Shadow DOM root.
`container`	`HTMLElement \| null`	`document.body`	Target parent element for Shadow DOM container mounting.
`privacy.mask`	`string[]`	`undefined`	Sensitive header & body keys to mask in network inspector (e.g. `['token', 'password']`).
`theme.mode`	`'dark' \| 'light' \| 'auto'`	`'dark'`	Theme mode setting (`'dark'`, `'light'`, or `'auto'`).
`theme.backgroundColor`	`string`	`undefined`	Primary drawer & floating badge background color CSS value.
`theme.cardBackgroundColor`	`string`	`undefined`	Floating cards & list item background color CSS value.
`theme.cardBorderColor`	`string`	`undefined`	Internal card outline border color CSS value.
`theme.borderColor`	`string`	`undefined`	Main container & divider line border color CSS value.
`theme.textColor`	`string`	`undefined`	Primary body text color CSS value.
`theme.textMutedColor`	`string`	`undefined`	Secondary / muted label text color CSS value.
`theme.accentColor`	`string`	`undefined`	Primary brand accent color for active tabs, toggles, and highlights.
`theme.errorColor`	`string`	`undefined`	Error badges & status indicator color CSS value.
`theme.warningColor`	`string`	`undefined`	Warning badges & status indicator color CSS value.
`theme.successColor`	`string`	`undefined`	Success status indicator color CSS value.
`theme.fontFamily`	`string`	`undefined`	Custom font family stack CSS value for all DevTools text inside Shadow DOM.
`interceptors.maxLogLimit`	`number`	`200`	Maximum number of console logs retained in memory.
`interceptors.maxNetworkLimit`	`number`	`100`	Maximum number of network requests retained in memory.
`interceptors.ignoreNetworkUrls`	`(string \| RegExp)[]`	`[]`	List of URL strings or RegExps to exclude from network interception.
`interceptors.enableConsoleInterceptor`	`boolean`	`true`	Enable or disable console log/warn/error interception.
`interceptors.enableFetchInterceptor`	`boolean`	`true`	Enable or disable `window.fetch` API interception.
`interceptors.enableXhrInterceptor`	`boolean`	`true`	Enable or disable `XMLHttpRequest` interception.
`interceptors.enableWebSocketInterceptor`	`boolean`	`true`	Enable or disable WebSocket frame interception.
`interceptors.enableSSEInterceptor`	`boolean`	`true`	Enable or disable EventSource (SSE) stream interception.

🎨 Theme Engine & Customization

mobile-devtools features a built-in theme engine that automatically calculates background brightness to maintain WCAG AAA readable text contrast:

<MobileDevTools
  title="Staging Debugger"
  icon="🚀"
  position="bottom-left"
  theme={{
    mode: 'dark',
    accentColor: '#10b981',
    backgroundColor: '#0c0c0e',
  }}
  styles={`
    .devtools-badge { border-radius: 12px; }
    .devtools-drawer { border-top-left-radius: 20px; border-top-right-radius: 20px; }
  `}
/>

📂 Monorepo Structure

mobile-devtools/
├── apps/
│   └── web/                    # React documentation & live playground app (Port 3000)
├── examples/
│   ├── react/                  # React 19 test harness app (Port 3001)
│   ├── vue/                    # Vue 3 test harness app (Port 3002)
│   ├── svelte/                 # Svelte 5 test harness app (Port 3003)
│   └── vanilla/                # Vanilla JS test harness app (Port 3004)
└── packages/
    ├── mobile-devtools/        # Main unified published npm package (Core + UI + React/Vue/Svelte/Vanilla Adapters)
    └── config/
        ├── eslint/             # Shared ESLint configuration (@mobile-devtools/eslint-config)
        └── typescript/         # Shared TypeScript configuration (@mobile-devtools/tsconfig)

🛠️ Development Setup

Prerequisites: Node.js >= 24.0.0 (v24.4.1+ recommended), pnpm 9.15.0

To build and run the project locally:

# Clone repository
git clone https://github.com/dewasemadi/mobile-devtools.git
cd mobile-devtools

# Install dependencies using pnpm
pnpm install

# Launch all apps & package watchers in dev mode
pnpm dev

# Run unit test suite (65 tests)
pnpm test

# Run unit tests with V8 coverage report
pnpm test:coverage

# Run Playwright E2E tests (21 tests across Chromium & Mobile Webkit)
pnpm test:e2e

# Build production bundles
pnpm build

📄 License

Distributed under the MIT License. See LICENSE for details.

Name		Name	Last commit message	Last commit date
.github		.github
apps/web		apps/web
docs		docs
examples		examples
packages		packages
.gitignore		.gitignore
.node-version		.node-version
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
RELEASE.md		RELEASE.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
turbo.json		turbo.json

Navigation Menu

Repository files navigation

Mobile DevTools

📌 Table of Contents

📸 Showcase

💡 Motivation & Why Use It?

✨ Core Capabilities

🏗️ Technical Architecture

🚀 Framework Quickstart

📦 Installation

⚛️ React Integration

💚 Vue 3 Integration

🔥 Svelte Integration

🧡 Svelte 4/5 Integration

🍦 Vanilla JS / Legacy Apps

⚙️ Full Configuration & Props Reference

🎨 Theme Engine & Customization

📂 Monorepo Structure

🛠️ Development Setup

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Mobile DevTools

📌 Table of Contents

📸 Showcase

💡 Motivation & Why Use It?

✨ Core Capabilities

🏗️ Technical Architecture

🚀 Framework Quickstart

📦 Installation

⚛️ React Integration

💚 Vue 3 Integration

🔥 Svelte Integration

🧡 Svelte 4/5 Integration

🍦 Vanilla JS / Legacy Apps

⚙️ Full Configuration & Props Reference

🎨 Theme Engine & Customization

📂 Monorepo Structure

🛠️ Development Setup

📄 License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages