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.

📖 Documentation — guides, API reference, and a live demo you can run in your browser.

Demo

Try it in your browser at lynx-console.pages.dev — the home page embeds the example app running on the Lynx Web Platform.

https://github.com/user-attachments/assets/dcd874bf-ff2e-4a98-ae03-d83de5fae31c

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

https://github.com/user-attachments/assets/539fe31a-aca4-468d-b673-3b070b21cd08

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

https://github.com/user-attachments/assets/edda4778-ab8d-4cb9-a3c5-bd8c42c81bde

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

https://github.com/user-attachments/assets/d231bdf5-71bb-483f-9bdb-5843279c1308

• 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 — height as a bottom sheet (200–700px), width as a side panel (280–720px); drag it outward to dismiss. Works with touch and with the mouse on web
• Adaptive Layout — Opens as a bottom sheet on tall screens and as a right side panel when the LynxView is wider than it is tall (unfolded foldable, tablet, landscape)
• Tab Visibility — Only tabs for initialized monitors are shown; uninitialized monitors are automatically hidden
• Filter Tabs — Turn on a tab to view only its entries. Tap another tab to switch right away; with nothing on, everything shows, and tapping the active tab again turns it off
• Custom Tabs — Add your own tabs via the customTabs prop, or give a tab a filter to show only the console logs you care about
• Lynx DevTool friendly — Network requests and FCP are also printed to the console as a summary line plus the entry, so they show up in Lynx DevTool (which has no Network panel).
• Light/Dark Theme support

Installation

yarn add lynx-console

Peer Dependencies

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

Usage

0. Configure Build (Required)

Add the following to your lynx.config.ts:

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

• console — on iOS, the Lynx runtime (JSC) injects a separate console object that is different from globalThis.console. Patches applied by initLogMonitor() won't take effect on iOS unless you replace the identifier at build time.
• fetch — depending on your build setup, network requests may not be logged unless it is replaced with lynx.fetch.

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>
  );
}

Filtering with tabs

Only one tab at the top of the console is active at a time. Tapping another tab switches to it, and with nothing active everything shows. Turning on Log reveals the level dropdown (Filter ▼); with Network active the body switches to the network-only view with match navigation. The search box looks at the printed text as well as the URL, headers and body of each network request, and a matched network row is expanded on the section that matched. While you scroll up to read, the list stops following new logs and counts what piled up as N new ↓.

Filtering console logs into a tab

A tab with filter becomes a filter tab that collects only the console entries that match.

const customTabs: CustomTab[] = [
  { key: "track", label: "Track", filter: "track" }, // string: the printed text contains it
  { key: "errors", label: "Errors", filter: (entry) => entry.level === "error" },
];

console.log("%ctrack%c screen_view", "color:#db2777;font-weight:bold", "", { screen: "home" }); // shows up once the Track tab is on

Pass renderEntry to draw each matched entry yourself — it applies when that tab is the only one active.

Reading from Lynx DevTool

Lynx DevTool has no Network panel, so each completed request is also printed as a %c-styled GET 200 https://… 123ms line plus the entry object, and every performance entry as pipeline loadBundle FCP 812.34ms. In the console they render as the same rows as the Network and Perf tabs. Pass initNetworkMonitor({ console: "plain" }) for unstyled text (logcat, CI) or { console: false } to turn it off. Use filter: isNetworkLog to collect these lines in a tab.

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 | | safeAreaInsetTop | string | "24px" | Top safe area inset (side panel layout only) | | customTabs | CustomTab[] | undefined | Additional custom tabs to display in the console | | initialPosition | { top?: number; left?: number; right?: number; bottom?: number } | { right: 16, bottom: 84 } | Initial position (px) of the floating button. Each side is independent, so you can anchor it to any corner (e.g. { top: 50, left: 16 }). When both top and bottom (or both left and right) are set, top/left win. Once the user drags the button, the saved position takes precedence. |

CustomTab

| Property | Type | Description | | --------------- | ----------------- | ------------------------------------- | | key | string | Unique identifier for the tab | | label | string | Tab label text | | renderContent | () => ReactNode | Content tab: renders the tab content | | filter | string \| RegExp \| (entry: LogEntry) => boolean | Filter tab: shows only matching console entries | | renderEntry | (entry: LogEntry) => ReactNode | Filter tab, optional: renders one matched entry when that tab is the only active one |

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 |