How FishUI Achieves Seamless Cross‑Platform UI Development for Xianyu

Background

As Xianyu’s front‑end architecture evolves, key technical facilities need to be built in‑house while embracing community solutions for scalability. The Kun cross‑platform framework lets developers deliver pages with plain JS/CSS/HTML, and the UI framework is shifting from the internal Rax to React. In this context, FishUI was created to fully adopt the React ecosystem, leverage Kun’s capabilities, and provide a highly usable, stable cross‑platform (Kun & web) UI component library.

Overall Design

Layered Architecture

FishUI consists of three layers: low‑level Kun container components, standard W3C‑compliant web components, and a top‑level cross‑platform component layer that abstracts away container differences. The cross‑platform layer aims to be rich and reusable, while the Kun‑specific layer stays thin to address only necessary scenarios.

Cross‑Platform Design

The library automatically detects the runtime environment via window.kun and executes the appropriate code, eliminating manual environment checks. It also normalizes attribute differences, provides a unified TypeScript API, and reduces template code, improving developer productivity.

Automatic environment detection based on window.kun Automatic smoothing of Kun and web attribute differences

Unified TypeScript interface declarations

Reduced template code for cleaner components

For example, rendering an image in a traditional approach requires separate code for each container, whereas FishUI allows a single declarative call that works in both environments.

Technical Choices

Language and Styling

React, TypeScript, and moduleCSS were chosen for component development. moduleCSS prevents style leakage in multi‑developer scenarios without exposing internal class names, ensuring backward compatibility and controlled customization via component props or CSS variables.

Monorepo Structure

FishUI adopts a monorepo with a single repository containing multiple npm packages—one per component. This approach offers on‑demand package imports, isolated development cycles, and fine‑grained tree‑shaking benefits compared to a single large bundle.

Dependency Management

pnpm is used for package installation, while lerna + nx manage multi‑package versioning and script execution. pnpm solves phantom dependencies, split‑version issues, and redundant installations by using a global cache and hard links.

Per‑Environment Build

During the build, a custom webpack loader parses the source AST with @babel/parser to replace window.kun with a boolean literal, enabling tree‑shaking to drop dead code for the opposite environment. This results in bundles that contain only the code needed for the target platform.

Automated Testing

Unit tests are written with Jest and React Testing Library, favoring a user‑centric testing approach over Enzyme’s implementation‑focused style. A typical test file demonstrates rendering a component and asserting its behavior.

Code Standards

FishUI follows Xianyu’s unified front‑end coding standards, including ESLint/TSLint rules and the f2elint tool from Alibaba’s front‑end specification, to ensure consistent quality across the codebase.

API Design Guidelines

Component APIs consist of mandatory properties (e.g., className, style) and custom properties specific to each component. Guidelines emphasize composability, controlled vs. uncontrolled patterns, extensibility via children or render functions, and sensible naming conventions.

Documentation Site

Component documentation is authored in Markdown and generated with Docusaurus, providing React‑based theming, MDX support, Algolia search, and custom features such as an interactive Playground (using @babel/standalone) and QR‑code previews for Kun and H5 environments.

Challenges and Future Work

Technical challenges include React’s inability to bind custom events directly on Kun tags, attribute mismatches between Kun and web standards, and limited test coverage for Kun environments. Planned solutions involve runtime hacks to intercept React.createElement, separate attribute handling, and mock implementations for Kun in Jest.

Beyond engineering, aligning front‑end and client‑side teams, expanding visual‑interaction integration, improving cross‑platform debugging, supporting additional frameworks, and applying FishUI to more business scenarios are ongoing goals.

Conclusion and Outlook

FishUI is in its early adoption phase, already delivering unified cross‑platform experience, reduced template code, and faster development cycles. Continued iteration will focus on tighter visual‑interaction coupling, richer multi‑framework support, and broader business adoption, ultimately becoming a cornerstone of Xianyu’s multi‑terminal front‑end ecosystem.