@neuradigi/debug-console

@neuradigi/debug-console

A tiny in-app console overlay. It mirrors your app's console.log/info/warn/error/debug and uncaught errors into a floating panel, so you can read logs inside the running app — no DevTools needed. It mirrors output (never swallows it), so DevTools keeps working too.

Built as a Web Component (Shadow DOM), so it drops into Angular, React, Vue, Svelte, or plain HTML with zero dependencies and no style conflicts.

• One call to set up
• Captures console.* + uncaught errors / promise rejections
• Filter, auto-scroll, download .log, clear
• Style-isolated, SSR-safe, zero runtime deps

Install

npm install @neuradigi/debug-console

No bundler? Import straight from a CDN — nothing to install:

<script type="module">
  import { initDebugConsole } from 'https://esm.sh/@neuradigi/debug-console';
  initDebugConsole();
</script>

Quick start

Call it once, as early as possible in your app's entry file:

import { initDebugConsole } from '@neuradigi/debug-console';

initDebugConsole();

A launcher button appears in the corner — click it to open the panel. That's it.

Options

Everything is optional — pass only what you want to change:

initDebugConsole({
  enabled: true,             // false = do nothing at all (use to switch off in production)
  max: 500,                  // max lines kept; oldest are dropped past this
  captureGlobalErrors: true, // also catch uncaught errors + unhandled promise rejections
  position: 'top-right',     // 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
  accent: '#22c55e',         // any CSS color/gradient for the launcher & active filter chips
  open: false                // true = start expanded instead of collapsed
});

Turn it off in production: initDebugConsole({ enabled: process.env.NODE_ENV !== 'production' }).

Framework setup

It's the same everywhere: call initDebugConsole() at the top of your entry file, before your app mounts — so even startup logs are caught. No tags or registration needed.

import { defineDebugConsole, startCapture } from '@neuradigi/debug-console';

startCapture();        // begin mirroring console.* + errors (no UI)
defineDebugConsole();  // register the <debug-console> element

<debug-console data-position="top-right"></debug-console>

Panel controls

Levels are colour-coded: error red, warn amber, info blue, log/debug gray.

API

Most apps only need initDebugConsole(). It returns a handle for programmatic control (or null when disabled / no DOM):

const dc = initDebugConsole();
dc?.show();      // open the panel
dc?.hide();      // close it
dc?.toggle();
dc?.clear();     // empty the buffer
dc?.destroy();   // remove the overlay

import { logger } from '@neuradigi/debug-console';

logger.entries;              // readonly LogEntry[] (oldest → newest)
logger.limit;                // configured buffer cap
logger.clear();              // empty the buffer
const off = logger.subscribe(e => {   // e is { type: 'add', entry } | { type: 'clear' }
  if (e.type === 'add') myTelemetry(e.entry);
});
// ...later: off();

type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
interface LogEntry { id: number; level: LogLevel; time: Date; text: string; }

Theming

The panel uses a fixed dark "terminal" look. Change the accent in one line:

initDebugConsole({ accent: '#22c55e' });

Or override any colour with a CSS custom property (they inherit through the shadow boundary):

debug-console { --dc-accent: #22c55e; --dc-bg: #0d1117; }

debug-console::part(launcher) { /* the corner button */ }
debug-console::part(panel)    { /* the sliding panel */ }

Notes & limits

• Captures log / info / warn / error / debug. Not console.trace/table/dir/group/assert.
• Native browser messages (failed network / CORS / CSP) only appear if your code logs them.
• Buffer is bounded (default 500); safely stringifies circular refs, bigint, and Error.
• Uses position: fixed — a transform/filter on an ancestor re-anchors it (standard CSS).
• SSR-safe: every call no-ops when there is no DOM.

Develop

npm install
npm run build   # bundle to dist/ (ESM + CJS + types)
npm run dev     # rebuild on change

Live demo: run npm run build, serve the repo root (npx serve .), and open /demo/.

License

MIT Neuradigi Technologies