한국어 | English

lynx-console

An in-app developer console that can be embedded in Lynx apps. View console logs, network requests, and performance metrics in real time.

Demo

Lynx-console-custom-tab.mp4

Scan the QR code above with the Lynx Explorer app to try the demo.

Features

• Console Logs — View output from console.log, console.error, and more in real time. Supports level filtering, keyword search, log clearing, and a built-in REPL
• Main Thread Console — Capture logs from the main thread alongside background thread logs

Lynx-console-log-filtering.mp4

• Network Monitor — Inspect method, status, headers, request body, and response of fetch requests

Lynx-console-network.mp4

• Performance Monitor — Track FCP (First Contentful Paint) and other performance metrics with raw entry details

Lynx-console-perf.mp4

• Floating Button — Displays the latest FCP value; tap to open the console, long-press and drag to reposition it
• Resizable Panel — Drag the handle to resize the console panel (200–700px); swipe down to dismiss
• Tab Visibility — Only tabs for initialized monitors are shown; uninitialized monitors are automatically hidden
• Custom Tabs — Add your own tabs to the console via the customTabs prop
• Light/Dark Theme support

Installation

yarn add lynx-console

Peer Dependencies

yarn add @lynx-js/react @lynx-js/types
yarn add -D @types/react

Note: Each monitor requires the corresponding Lynx API to be available at runtime. If lynx.fetch is not present, initNetworkMonitor() will be skipped with a warning. Likewise, initPerformanceMonitor() requires lynx.performance.

Usage

0. Configure Build (Required for iOS)

On iOS, the Lynx runtime (JSC) injects a separate console object that is different from globalThis.console. This means patches applied by initLogMonitor() won't take effect on iOS unless you explicitly replace the console identifier with globalThis.console at build time.

Add the following to your lynx.config.ts:

export default defineConfig({
  source: {
    define: {
      console: "globalThis.console",
    },
  },
});

1. Initialize Monitors

Call the monitoring functions at your app's entry point. This setup must run before the LynxConsole component is rendered.

import {
  initLogMonitor,
  initMainThreadConsole,
  initNetworkMonitor,
  initPerformanceMonitor,
} from "lynx-console/setup";

initLogMonitor();
initMainThreadConsole();
initNetworkMonitor();
initPerformanceMonitor();

Note: initLogMonitor() must be called before initMainThreadConsole(), as the main thread console depends on the log monitor being initialized first.

2. Render the Component

import LynxConsole from "lynx-console";

function App() {
  return (
    <view>
      {/* Your app content */}
      <LynxConsole theme="light" safeAreaInsetBottom="34px" />
    </view>
  );
}

const LynxConsole = lazy(() => import("lynx-console"));

function App() {
  return (
    <view>
      {/* Your app content */}
      <Suspense>
        <LynxConsole theme="light" safeAreaInsetBottom="34px" />
      </Suspense>
    </view>
  );
}

Adding Custom Tabs

You can add your own tabs to the console using the customTabs prop.

import LynxConsole, { type CustomTab } from "lynx-console";

const customTabs: CustomTab[] = [
  {
    key: "debug",
    label: "Debug",
    renderContent: () => <text>Custom debug content</text>,
  },
];

function App() {
  return (
    <view>
      <LynxConsole customTabs={customTabs} />
    </view>
  );
}

Controlling with ref

You can programmatically open and close the console using LynxConsoleHandle.

import { type LynxConsoleHandle } from "lynx-console";
import { useRef } from "@lynx-js/react";

const LynxConsole = lazy(() => import("lynx-console"));

function App() {
  const consoleRef = useRef<LynxConsoleHandle>(null);

  const toggleConsole = () => {
    if (consoleRef.current?.isOpen()) {
      consoleRef.current.close();
    } else {
      consoleRef.current?.open();
    }
  };

  return (
    <view>
      <Suspense>
        <LynxConsole ref={consoleRef} />
      </Suspense>
    </view>
  );
}

You can also integrate it with a back press handler so that the console closes when the back button is pressed.

API

LynxConsole Props

Prop	Type	Default	Description
theme	"light" | "dark"	"light"	Console UI theme
safeAreaInsetBottom	string	"50px"	Bottom safe area inset
customTabs	CustomTab[]	undefined	Additional custom tabs to display in the console

CustomTab

Property	Type	Description
key	string	Unique identifier for the tab
label	string	Tab label text
renderContent	() => ReactNode	Function that renders the tab content

LynxConsoleHandle

Method	Description
open()	Opens the console
close()	Closes the console
isOpen()	Returns whether the console is open

Monitor Initialization Functions

Function	Description
initLogMonitor()	Captures console.log, console.error, etc.
initMainThreadConsole()	Captures console output from the main thread
initNetworkMonitor()	Intercepts and records fetch requests
initPerformanceMonitor()	Collects performance metrics