AI-Powered React-to-Kuikly Migration: 90% Code Adoption, 90% Load Time Cut, 3 Days → 1 Day

Background

Kuikly is Tencent's open-source high-performance cross-platform framework supporting Android, iOS, HarmonyOS, Web, mini-programs, and Mac via Kotlin. QQ Music has built over 200 pages with Kuikly but still maintained many legacy React H5 pages. The team aimed to unify these pages onto Kuikly to gain native rendering performance, low-latency loading, and consistent multi-platform experience, solving H5 pain points like slow loads and interaction lag.

Architecture and Process Overview

In collaboration with the Kuikly team, QQ Music built an AI-powered translation workflow adopting a "core Agent + business configuration" architecture. This slot-based design decouples process logic from business knowledge, enabling other teams to onboard by providing a dedicated business Skill. The workflow comprises four main stages:

Initialization & Preprocessing : Resource preprocessing and cache checks. Scripts handle inline assets (base64, SVG) to avoid token waste, and a cache layer prevents redundant work.

Keyword & Knowledge Collection : Precise retrieval via keyword extraction yields high-density, high-accuracy knowledge.

Code Generation : Progressive, per-file conversion ensures accuracy for each file.

Verification & Delivery : Self-checks and compilation validation guarantee code quality.

Human intervention points are inserted at key nodes, with critical data persisted to support checkpoint resume.

Key Solution Evolutions

3.1 Smart Keyword Extraction & On-Demand Knowledge Loading

Early attempts injected all framework docs and business rules into the prompt, causing token bloat and AI "attention dilution" that led to frequent code errors. The team switched to a "smart scan + on-demand load" strategy:

Precise Scan : Pre-conversion source-code scan identifies exactly which components and business scenarios the current page uses.

Dynamic Assembly : Only core framework knowledge is fully loaded; component docs and business rules are loaded strictly on demand. This drastically cuts token usage and focuses the model's attention, significantly improving generation accuracy.

3.2 Inline Resource Preprocessing

React projects often contain inline base64 images or long SVG nodes. Direct conversion yielded very low success rates because these meaningless characters consumed context windows and distracted the model from core logic. A dedicated pre-processing script (step 2) automatically extracts inline resources, replaces them with concise local file references, resolves cross-directory alias paths (e.g., @/), and normalizes framework-level differences such as converting SVG color to tintColor.

3.3 Progressive Conversion Strategy

For large complex pages, a one-shot "black-box generation" triggers model attention decay and severe hallucinations. The team designed a progressive architecture turning migration into "divide and conquer".

One-Shot Full Generation (Rejected)

Core Idea : Feed knowledge base and all React source to AI once, generate all Kuikly files.

Pros : Minimal process, low dev cost, theoretically complete context.

Cons : Hard context-window limit, attention decay, zero controllability, extremely high error-recovery cost.

Stepwise Progressive Generation (Adopted)

Core Idea : Analyze structure first, then convert file by file, finally tidy architecture.

Pros : Controllable token usage, accurate business logic, stable tool calls, low error-recovery cost.

3.4 Progress Persistence & Checkpoint Resume

Complex AI translation tasks often require full re-run on any failure, unacceptable for large projects. The team introduced a dual mechanism: a progress recording system and key-node archival with confirmation prompts.

Progress Recording System : Each page task has an independent progress file at react2kuikly/[page]/cache/progress.md supporting two granularity levels.

3.5 Dual Quality Assurance

During-Conversion Checks

Immediate per-file logic validation after each file translation.

Instant business checklist verification and correction.

Post-Conversion Checks

Global logical and functional completeness validation.

Compilation check with iterative fixing until clean build.

3.6 Pluggable Business Skill Design

To enable reuse across teams, the core Skill is fully decoupled from business rules:

react2kuikly (core)
    └── calls ──▶ qqmusic-react2kuikly (business Skill)
    └── calls ──▶ other-business Skill (self-service onboarding)

Business Skills declare resource paths via PATH_CONFIG; core scripts resolve them dynamically, requiring no core-code changes for new business onboarding.

Migration Results

Nine React pages and three shared components have been migrated via the AI workflow. For medium-complexity pages, the development cycle (code adjustment + testing) dropped from an estimated 3+ days to under 1 day. AI-generated code adoption exceeds 90%.

Beyond efficiency, user experience saw a qualitative leap: leveraging Kuikly's native high-performance rendering, page load time decreased by 90% , and overall performance surpassed the original React version across Android, iOS, and HarmonyOS, eliminating H5 container bottlenecks.

Future Plans

The team will extend the AI translation framework beyond the mature React and Vue conversions, and is already exploring native app code-to-Kuikly migration with promising early results. They aim to refine multi-framework and native-app rule adapters, building a generalized cross-platform migration AI solution. The entire AI translation toolchain is being prepared for open-source release to share technical outcomes and practical experience with the community.

Kuikly Repositories

Kuikly is now open-source. Repositories and documentation:

GitHub: https://github.com/Tencent-TDS/KuiklyUI Official Site: https://kuikly.tds.qq.com/Introduction/arch.html AI Repository:

https://kuikly.tds.qq.com/AI/