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.

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 — 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
• Multi-select Filter Tabs — Turn on several tabs at once to view only the selected tabs. With nothing on, everything shows; tap an active tab again to turn 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

The tabs at the top of the console are multi-select. With nothing active everything shows, and several active tabs are a union. Turning on Log reveals the level dropdown (Filter ▼); with Network alone 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