@mugenlabs/logtape-devtools 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yago Gonzalez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @mugenlabs/logtape-devtools
+
+A [TanStack DevTools](https://tanstack.com/devtools) plugin for inspecting [LogTape](https://logtape.org) logs in the browser.
+
+Filter, search, and inspect structured logs in real time — without leaving the browser DevTools overlay.
+
+## Features
+
+- **Live log streaming** — see logs as they happen
+- **Level filtering** — toggle trace, debug, info, warning, error, fatal
+- **Category search** — filter by logger category
+- **Structured inspection** — expand logs to view properties and stack traces
+- **Pause & resume** — freeze the log stream to inspect entries
+
+## Installation
+
+```bash
+pnpm add @mugenlabs/logtape-devtools @logtape/logtape @tanstack/react-devtools
+```
+
+## Quick Start
+
+### 1. Configure the LogTape sink
+
+```ts
+import { configure } from "@logtape/logtape";
+import { createDevtoolsSink } from "@mugenlabs/logtape-devtools";
+
+await configure({
+  sinks: { devtools: createDevtoolsSink() },
+  loggers: [{ category: ["app"], sinks: ["devtools"], lowestLevel: "debug" }],
+});
+```
+
+### 2. Add the DevTools plugin
+
+```tsx
+import { TanStackDevtools } from "@tanstack/react-devtools";
+import { createLogTapeDevtoolsPlugin } from "@mugenlabs/logtape-devtools";
+
+const logtapePlugin = createLogTapeDevtoolsPlugin();
+
+function App() {
+  return (
+    <>
+      {/* your app */}
+      <TanStackDevtools plugins={[logtapePlugin]} />
+    </>
+  );
+}
+```
+
+## API
+
+### `createDevtoolsSink(options?)`
+
+Creates a LogTape sink that forwards log records to the devtools store.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `store` | `LogStore` | `defaultLogStore` | Custom log store instance |
+| `captureStackTrace` | `boolean` | `true` (dev only) | Capture stack traces |
+| `stackTraceDepth` | `number` | `20` | Max stack trace frames |
+
+### `createLogTapeDevtoolsPlugin(options?)`
+
+Creates the TanStack DevTools plugin component.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `store` | `LogStore` | `defaultLogStore` | Custom log store instance |
+
+### `createLogStore(options?)`
+
+Creates a standalone log store for advanced use cases.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxRecords` | `number` | `1000` | Maximum records to retain |
+
+## Demo
+
+See the live demo and full documentation at [logtape-devtools.mugenlabs.dev](https://logtape-devtools.mugenlabs.dev/).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Sink } from '@logtape/logtape';
+
+type LogLevel = "trace" | "debug" | "info" | "warning" | "error" | "fatal";
+declare const LOG_LEVELS: LogLevel[];
+interface DevtoolsLogRecord {
+    /** Source location of the log call (only present when `experimentalCaptureStackTrace` is enabled). */
+    caller?: string;
+    category: string[];
+    id: string;
+    level: LogLevel;
+    message: unknown[];
+    messageText: string;
+    properties: Record<string, unknown>;
+    timestamp: number;
+}
+
+type Listener = () => void;
+interface LogStore {
+    addRecord(record: DevtoolsLogRecord): void;
+    clear(): void;
+    getSnapshot(): DevtoolsLogRecord[];
+    setMaxSize(size: number): void;
+    subscribe(listener: Listener): () => void;
+}
+declare function createLogStore(maxSize?: number): LogStore;
+/** Default shared store instance used when no custom store is provided */
+declare const defaultLogStore: LogStore;
+
+interface LogTapeDevtoolsPluginOptions {
+    /** Whether to open the devtools panel by default. Default: true */
+    defaultOpen?: boolean;
+    /** Plugin display name. Default: "LogTape" */
+    name?: string;
+    /** Custom log store instance. Must match the store passed to createDevtoolsSink. */
+    store?: LogStore;
+}
+/**
+ * Creates a TanStack DevTools plugin config object for LogTape.
+ *
+ * Usage:
+ * ```tsx
+ * import { TanStackDevtools } from "@tanstack/react-devtools";
+ * import { createLogTapeDevtoolsPlugin } from "@mugenlabs/logtape-devtools";
+ *
+ * <TanStackDevtools plugins={[createLogTapeDevtoolsPlugin()]} />
+ * ```
+ */
+declare const createLogTapeDevtoolsPlugin: (options?: LogTapeDevtoolsPluginOptions) => {
+    defaultOpen: boolean;
+    id: string;
+    name: string;
+    render: react_jsx_runtime.JSX.Element;
+};
+
+interface Props {
+    store: LogStore;
+}
+declare const LogTapeDevtoolsPlugin: ({ store }: Props) => react_jsx_runtime.JSX.Element;
+
+interface DevtoolsSinkOptions {
+    /**
+     * Capture the source location of each log call via stack trace parsing.
+     *
+     * **Experimental / dev-only** — relies on `new Error().stack` which is
+     * engine-dependent. Automatically disabled in production builds (when
+     * `process.env.NODE_ENV === "production"`) because minified bundles
+     * produce meaningless file/line references. Note that source maps do not
+     * help here — browsers do not apply source maps to `Error.stack`.
+     *
+     * Set `forceStackTrace` to `true` to override the production guard — useful
+     * when your production build ships unminified code.
+     *
+     * @default true
+     */
+    experimentalCaptureStackTrace?: boolean;
+    /**
+     * Force stack trace capture even in production builds.
+     * Only has an effect when `experimentalCaptureStackTrace` is `true`.
+     *
+     * @default false
+     */
+    forceStackTrace?: boolean;
+    /** Custom log store instance. Defaults to the shared store. */
+    store?: LogStore;
+}
+/**
+ * Creates a LogTape sink that forwards log records to the devtools panel.
+ *
+ * Usage:
+ * ```ts
+ * import { configure } from "@logtape/logtape";
+ * import { createDevtoolsSink } from "@mugenlabs/logtape-devtools";
+ *
+ * await configure({
+ *   sinks: { devtools: createDevtoolsSink() },
+ *   loggers: [
+ *     { category: ["app"], lowestLevel: "debug", sinks: ["devtools"] },
+ *   ],
+ * });
+ * ```
+ */
+declare function createDevtoolsSink(options?: DevtoolsSinkOptions): Sink;
+
+export { type DevtoolsLogRecord, type DevtoolsSinkOptions, LOG_LEVELS, type LogLevel, type LogStore, LogTapeDevtoolsPlugin, type LogTapeDevtoolsPluginOptions, createDevtoolsSink, createLogStore, createLogTapeDevtoolsPlugin, defaultLogStore };