Zhin.js

English

简体中文

English

简体中文

Appearance

中文版

Generated reference snapshot

Original Cubic page · captured 2026-09-23 · source commit. This AI-generated page has not been verified against the current code. Use the Zhin documentation for current behavior and see known corrections.

Relevant source files

The following files were used as context for generating this wiki page:

Authoring Console Pages ​

Console Pages allow developers to extend the Zhin.js Remote Console with custom React-based user interfaces. These pages integrate directly into the Plugin Runtime, enabling plugins to provide management dashboards, interactive tools (like the Agent Sandbox), or visualization components.

The system uses a convention-over-configuration approach where pages placed in specific directories are automatically discovered, built, and served to the browser.

Project Structure and Conventions ​

You define Console Pages within the pages/ directory of a plugin. Each page exists in its own subdirectory containing an index.tsx file.

Directory PathFeature TypePurpose
pages/<name>/index.tsxzhin.pageDefines a new navigation entry and view.
pages/nav/index.tsxzhin.layoutOverrides the navigation/layout for the plugin scope.
pages/footer/index.tsxzhin.layoutOverrides the footer layout for the plugin scope.

Sources: packages/toolkit/create-zhin/src/workspace.ts:741-766, packages/toolkit/create-zhin/template/skills/plugin-develop/SKILL.md:25-35

Scaffolding a Page ​

A standard page includes a metadata declaration using definePage and a React component as the default export.

typescript
import { definePage } from '@zhin.js/console-contract';

export const meta = definePage({
  title: 'My Custom Page',
  order: 10,
});

export default function MyPage() {
  return <div>Welcome to the Zhin Console!</div>;
}

Sources: packages/toolkit/create-zhin/src/workspace.ts:741-750, packages/console/pagemanager/tests/client-build/client-build.test.ts:25-29

Page Metadata ​

The meta export provides the Remote Console with information about how to display and route the page. Zhin extracts this metadata statically during the build process; it must not contain dynamic logic or process environment variables.

Metadata Properties ​

PropertyTypeDescription
titlestringThe display name of the page in the navigation menu.
iconstring(Optional) Icon name to display alongside the title.
ordernumber(Optional) Sorting priority in the menu.
hideInNavbooleanIf true, the page is accessible via route but hidden from the menu.
requiredRolesstring[](Optional) Permissions required to access the page.

Sources: packages/console/pagemanager/src/client-build/typescript-builder.ts:114-125, packages/console/pagemanager/tests/client-build/client-build.test.ts:37-43

The Build Process ​

The TypeScriptClientBuilder compiles TSX source files into browser-compatible JavaScript artifacts. This process involves three primary stages: metadata extraction, bundling, and import rewriting.

The diagram shows the transformation of a TSX source file into a client-side artifact. Sources: packages/console/pagemanager/src/client-build/typescript-builder.ts:54-85

Register Wrapper ​

The builder wraps convention-based pages in a register(api) function. This allows the Remote Console to mount the component and add routes dynamically. Sources: packages/console/pagemanager/src/client-build/typescript-builder.ts:153-195

Import Rewriting ​

Since the browser cannot resolve bare Node.js imports (e.g., react), the builder rewrites these imports to canonical ESM paths, typically pointing to the Console Host's /esm/ endpoint or an external CDN like esm.sh. Sources: packages/console/pagemanager/src/client-build/typescript-builder.ts:74-78, basic/cli/src/plugin-runtime/console/page-renderer.ts:48-54

Hot Module Replacement (HMR) ​

The Zhin Plugin Runtime supports HMR for Console Pages. When you modify a page source file, the HmrCoordinator triggers a rebuild of that specific artifact and atomically replaces it in the active RuntimeSnapshot.

The sequence diagram illustrates the atomic replacement of page artifacts during development. Sources: packages/im/runtime/tests/console-feature-hmr.test.ts:55-75

If a build fails (e.g., due to dynamic metadata or syntax errors), the runtime retains the previous successful snapshot to ensure stability. Sources: packages/im/runtime/tests/console-feature-hmr.test.ts:76-80

Rendering the Shell ​

The Console Host provides a base HTML shell that loads the built page modules. For simple pages or the built-in Sandbox, the shell includes:

  1. Import Map: Defines where to find core libraries like React.
  2. Plugin Navigation: Renders components provided by zhin.layout features.
  3. Page Root: A mounting point for the page component.

Sources: basic/cli/src/plugin-runtime/console/page-renderer.ts:33-66

Sandbox Fallback ​

When no React UI runtime is available or for the specific sandbox page, the system provides a lightweight fallback script that handles message logs and composition via a standard WebSocket connection. Sources: basic/cli/src/plugin-runtime/console/page-renderer.ts:73-125

Implementation Constraints ​

Console Pages provide a powerful way to visualize bot state and provide interactive controls by leveraging a specialized build pipeline that bridges the gap between Node.js plugin code and browser-side React components.