MDev

In-browser developer tools built with TypeScript, vanilla DOM APIs, and Shadow DOM isolation.

MDev is an embedded, framework-agnostic developer toolbar for inspecting and debugging web pages directly inside the browser. It is especially useful where native DevTools are unavailable: mobile browsers, embedded WebViews, smart TVs, and staging environments.

Website and documentation: https://moo-m.github.io/mdevweb/

Table of Contents

• Key Features
• Installation
• Quick Start
• Usage in Frameworks
• Using MDev in Development Only
• Window Controls
• Modules
• API Reference
• Global State
• Browser Support
• Notes and Limitations
• Troubleshooting
• Contributing
• Changelog
• Links
• License

Key Features

• No external UI dependencies. Built with TypeScript and native Web APIs, with no UI framework.
• Shadow DOM isolation. The MDev UI is isolated from the host page, so your site's CSS cannot break it and it cannot break your site.
• Mobile and touch friendly. Floating windows you can move, resize, hide, and close, with two-finger gestures on touch screens.
• Console app. Color-coded logging, conditional output (test), timers (time / timeEnd), and an object tree viewer.
• Elements inspector. A live tree of the DOM, kept in sync with the page through MutationObserver.
• Application manager. Manage localStorage, sessionStorage, and cookies. Browse IndexedDB, Cache Storage, and Service Workers.
• Sources explorer. Search, preview, copy, or download scripts, styles, images, media, and fonts.

Installation

npm

npm install @moo-m/mdev

CDN

For quick tests or static HTML pages without a bundler:

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/@moo-m/mdev/MDev.js';
</script>

Pin a specific version to avoid unexpected changes:

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/@moo-m/[email protected]/MDev.js';
</script>

Quick Start

Import the package once in your application entry file:

import '@moo-m/mdev';

// MDev creates its floating dock on the page automatically.

Then use the dock to open Console, Elements, Application, or Sources, and call the logging helpers from anywhere in your code:

// Color-coded logs
green('Success:', 'Data fetched successfully');
red('Error:', 'Failed to load user profile');
blue('Info:', 'Session renewed');
yellow('Warning:', 'Storage usage is close to the quota');

// Conditional output
test(users.length > 0, 'Users list loaded', users);

// Timing
time('DataRender');
// ... heavy work ...
timeEnd('DataRender');

// Clear the MDev console
clear();

The helpers are also available on window:

window.red('Something went wrong');

Printing from any value

You can also print directly from any value by calling the helper as a method on it. The same methods (green, red, blue, yellow, ...) exist on every data type:

'Saved successfully'.green();       // string
(404).red();                        // number
true.blue();                        // boolean
[1, 2, 3].yellow();                 // array
({ id: 1, name: 'Sara' }).green();  // object
user.name.blue();                   // any property or variable

This is handy for logging in the middle of an expression without a separate statement. Use whichever style fits: global function, window.*, or a method on the value.

TypeScript: if your compiler reports that green, red, etc. are not defined, access them through window or add a global declaration file (for example mdev.d.ts) that declares them.

Usage in Frameworks

MDev is framework-agnostic. Import it once in your entry file, before or after your app mounts.

React / Vite

// src/main.tsx
import '@moo-m/mdev';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(<App />);

Vue

// src/main.ts
import '@moo-m/mdev';
import { createApp } from 'vue';
import App from './App.vue';

createApp(App).mount('#app');

Plain HTML

<script type="module">
  import 'https://cdn.jsdelivr.net/npm/@moo-m/mdev/MDev.js';
</script>

Using MDev in Development Only

MDev is designed for development and testing. Load it conditionally so it never reaches production users:

// Vite
if (import.meta.env.DEV) {
  await import('@moo-m/mdev');
}

// Webpack / Node-based bundlers
if (process.env.NODE_ENV !== 'production') {
  await import('@moo-m/mdev');
}

// Staging only, via a query flag
if (location.search.includes('mdev=1')) {
  await import('@moo-m/mdev');
}

Window Controls

Every app opens in its own floating window.

| Action | How | | --- | --- | | Resize | Drag the bottom-right corner, or pinch with two fingers on a touch screen | | Move | Drag the window with two fingers, or by its title bar | | Show / hide | Tap the app icon in the dock | | Close | Tap x at the top right of the window |

Modules

Console (c)

• Custom logging: green, red, blue, yellow, test, time, timeEnd.
• Data formatter: primitives, arrays, and objects are shown as expandable trees.
• Detached inspection: open large objects in their own window.
• Filter bar: filter by success, error, warn, info, test, or time.

Elements (e)

• Abstract Data Tree (ADT): converts the document into a nested structure of tags, attributes, text, and comments.
• Live tracking: MutationObserver follows attribute changes, added or removed nodes, and text changes.
• Tag and attribute viewer: shows tag names, IDs, classes, and other attributes.

Application (a)

• localStorage and sessionStorage: view, search, add, edit, and delete items, with confirmation before destructive actions.
• Cookies: read, add, and delete cookies available to document.cookie.
• IndexedDB: browse databases, object stores, record counts, and records as formatted JSON.
• Cache and Service Workers: list cache names and Service Worker registrations, including scope, script URL, and state.

Sources (s)

• Resource collector: the document, inline and external scripts, styles, images, audio, video, and fonts.
• Previewer: text and code, images, and native audio and video controls.
• Export: copy text content to the clipboard or download it as a file.

API Reference

All helpers are global functions (also available on window).

| Method | Type | Description | | --- | --- | --- | | green(...data) | success | Logs a success message. | | red(...data) | error | Logs an error message. | | blue(...data) | info | Logs an informational message. | | yellow(...data) | warn | Logs a warning. | | test(condition, ...data) | test | Shows the data when condition is truthy. | | time(label) | time | Records the start of a timer. | | timeEnd(label) | time | Records the end of a timer. | | clear() | n/a | Clears the displayed and stored messages. |

Printing methods

Every logging helper can be called in three ways:

| Style | Example | | --- | --- | | Global function | green('Done') | | On window | window.green('Done') | | As a method on any data type | 'Done'.green(), (42).red(), [1, 2].blue(), ({ a: 1 }).yellow() |

The method form is available on any value through non-enumerable Object.prototype properties (see Notes and Limitations).

Global State

MDev keeps its state on window.MDev:

interface MDevGlobal {
  host: ShadowRoot | null;

  screens: {
    console:     { activate: boolean };
    elements:    { activate: boolean };
    application: { activate: boolean };
    sources:     { activate: boolean };
  };
}

| Property | Description | | --- | --- | | host | The Shadow DOM root that contains the MDev UI, or null before initialization. | | screens.<name>.activate | Whether the given app window is currently active. |

Browser Support

MDev targets modern browsers that support ES modules, Shadow DOM, and MutationObserver, including current versions of Chrome, Edge, Firefox, Safari, and their mobile and WebView counterparts.

Notes and Limitations

• The logging helpers are also added to Object.prototype as non-enumerable properties, so value.green() works. Keep this in mind if you use libraries that rely on native prototypes.
• The native console.log is not forwarded to the MDev console. Use the MDev helpers above.
• Cookies are limited by the browser. HttpOnly cookies cannot be read from JavaScript.
• Cross-origin sources need valid CORS headers to be previewed. Otherwise, they may be listed as unavailable.
• Cache Storage and Service Workers are read-only for now.
• MDev is designed for development and testing. Keep it out of your production build (see Using MDev in Development Only).

Troubleshooting

The dock does not appear. Make sure the package is imported once in your entry file and that the code runs in a browser, not during server-side rendering. In SSR frameworks, import it inside a client-only block.

green / red is not defined (TypeScript). Use window.green(...) or add a global type declaration for the helpers.

Some sources show as unavailable. The resource is cross-origin and does not send CORS headers.

My console.log output is missing. MDev does not forward the native console. Use green, red, blue, or yellow.

Contributing

Issues and pull requests are welcome.

1. Fork the repository and create a branch.
2. Make your changes and test them in a browser.
3. Open a pull request describing the change.

Report bugs or suggest features at https://github.com/moo-m/MDev/issues.

Changelog

See GitHub Releases for version history.

Links

• Website: https://moo-m.github.io/mdevweb/
• npm: https://www.npmjs.com/package/@moo-m/mdev
• GitHub: https://github.com/moo-m/MDev
• Issues and suggestions: https://github.com/moo-m/MDev/issues
• jsDelivr: https://www.jsdelivr.com/package/npm/@moo-m/mdev

License

ISC