English | 简体中文
Documentation · DeepWiki · GitHub Release · npm organization
Varo provides components and Blocks for Vue 3 mobile H5 applications and weapp-vite mini programs. Install source for your target through the Registry, then edit and maintain it in your application.
@varo-ui/cli— installs editable Registry source for the selected deployment profile@varo-ui/headless— framework- and DOM-neutral state machines, events, controlled-state contracts, and utilities@varo-ui/h5— tree-shakeable Vue components for mobile H5 products@varo-ui/weapp— native Wevu.vuesource and a resolver for theweapp-vitecompiler, not a Vue render runtime@varo-ui/theme— shared theme tokens and providers@varo-ui/ai— safe Markdown models, text pacing, and thread-version helpers; chat state and transport come directly from TanStack AI
- H5 components: styled Vue components and DOM primitives, with editable Registry source
- Native components: target-specific Wevu SFCs; npm and Registry installations derive from the same authored source
- Agent Core: safe incremental Markdown AST, Markstream text pacing on H5, timed-frame text pacing on mini programs, and thread-version helpers only
- Agent UI: conversation, workspace, advanced, and RAG source units plus Agent Chat and Agent Workspace Blocks for scoped context, retrieval, tasks, thread versions, streaming, tools, approvals, code, diffs, citations, media, tables, and workflows
- Dual-target Blocks: Login Form, Profile Card, Profile Edit, Product List, Order Filter, Agent Chat, and Agent Workspace
- AI commerce demo: explicitly local TanStack AG-UI streams, reasoning and tool presentation, purchase/return approval UI, order history, and address configuration; not a live provider integration
- Renderer families:
h5andweapp; deployment profiles are listed below - Mini-program styling: Tailwind CSS v4,
weapp-tailwindcss, and@weapp-tailwindcss/merge - Mini-program debugging: built-in MCP, DevTools console bridge, Automator screenshots, and runtime smoke checks
- The core Weapp Registry components draw on features shared by Vant Weapp, NutUI, TDesign Mobile Vue, and TDesign MiniProgram.
- Motion and Agent interaction patterns reference Beautiful UI and beUI, while production code remains native to Vue and mini-program runtimes.
- A component's supported platforms are declared in its
registry/**/registry.jsonmanifest and those of all its dependencies. An H5 catalog entry or browser example does not establish native support. - TanStack AI owns AG-UI events, active messages, stream state, and aborts. H5 uses
@tanstack/ai-vue; native uses@tanstack/ai-clientwith Wevu. Varo's Markdown and text pacing are presentation-only: H5 uses Markstream Core, while mini programs use the same safe AST with timed scheduling independent ofrequestAnimationFrame. registry/component-tiers.v0.1.jsonrecords product tiers. The manifests and profile table inpackages/registry/src/index.tsdetermine which platforms an installation supports.
Write components in registry/components/**, Blocks in registry/blocks/**, and styles in registry/themes/**. Run pnpm sync:registry to generate packages/ui-h5/src, packages/ui-weapp/native, playground copies, and the docs Agent source and support catalog. Make changes in the Registry source; generated files should not be edited directly.
packages/shared defines the shared ReactiveRuntime interface. @varo-ui/headless provides framework- and platform-neutral interaction logic. H5 handles DOM rendering, focus, and body-scroll locking; native SFCs use the headless logic through wevu, without Vue render primitives.
themes/base contains tokens and foundation rules. Each component's manifest declares its CSS; Agent tokens and helpers come from the optional themes/agent dependency. H5 source imports all CSS needed by the component and its dependencies. Native apply-shared components load those styles through the application stylesheet.
| Install target | Renderer | Compiler platform | Host / maturity |
|---|---|---|---|
h5 |
h5 |
Browser build | Browser / stable |
weapp |
weapp |
weapp |
WeChat mini program / stable |
alipay |
weapp |
alipay |
Alipay mini program / experimental |
tt |
weapp |
tt |
Douyin mini program / experimental |
xhs |
weapp |
xhs |
Xiaohongshu mini program / experimental |
donut-android |
weapp |
weapp |
Donut Android / experimental |
donut-ios |
weapp |
weapp |
Donut iOS / experimental |
donut-ohos |
weapp |
weapp |
Donut OpenHarmony / experimental |
To install one of the six experimental profiles, the selected components and every dependency must explicitly support it. If any item does not, the CLI fails before writing files instead of falling back to Weapp. Representative supported components are button, input, input-otp, form, checkbox, switch, drawer, card, and icon, with their required utilities and themes. Check the manifests for the exact list. This does not certify the full catalog or Agent UI on those platforms.
Native AI clients enable the Web Runtime configuration: weapp.appPrelude.webRuntime: { enabled: true, networkDefaults: { request: { enableChunked: true } } }. Use TanStack's standard fetch adapter, not a bespoke wx.request transport. Streaming requires real status, headers, and incremental chunks from the host. Donut uses the WeChat compiler and selects its host through mini-android, mini-ios, or mini-ohos metadata, not a separate compiler target. See runtime evidence limits for SDK, IDE, AppID, signing, and device requirements.
# Native mini-program SFCs
pnpm dlx @varo-ui/cli add --target weapp button input card
# H5 source
pnpm dlx @varo-ui/cli add --target h5 button input card
# Experimental profile: only explicitly admitted source
pnpm dlx @varo-ui/cli add --target alipay button input input-otp form checkbox switch drawer card
# Dual-target business Block
pnpm dlx @varo-ui/cli add --target weapp blocks/product-list
# Dual-target Agent Chat Block
pnpm dlx @varo-ui/cli add --target weapp blocks/agent-chat
pnpm dlx @varo-ui/cli add --target h5 blocks/agent-chat
# Deliberately install the full Agent UI suite
pnpm dlx @varo-ui/cli add --target weapp components/agent-ui
pnpm dlx @varo-ui/cli add --target h5 components/agent-ui
# High-consensus mini-program components
pnpm dlx @varo-ui/cli add --target weapp action-sheet collapse dialog list notice-bar popover skeleton stepsInstall the npm dependencies listed by the CLI yourself. Existing files are kept by default. Review local customizations before using --force, which replaces files without merging your changes.
For native source installs, load every installed src/styles/*.css file globally using weapp.styles entries with include: 'app.vue', with varo.css first. Do not import these global styles from component-local WXSS: page tokens and global selectors do not belong there. Native npm consumers put @import "@varo-ui/weapp/style.css"; in local src/package.css and register { source: 'package.css', include: 'app.vue' } globally, not an absolute package path. See the native package setup and apps/platform-smoke/vite.config.mjs.
- Native rendering:
@varo-ui/weappexports native SFCs compiled by Wevu/weapp-vite, not Vue render functions. Direct imports such as@varo-ui/weapp/components/v-button.vueare supported.@varo-ui/weapp/resolverresolves locally installed Registry SFCs; there is no@varo-ui/weapp/primitivesentry. - H5 imports: use
@varo-ui/h5or@varo-ui/h5/primitives. For editable code, install Registry source.@varo-ui/h5/style.cssand the CSS-only@varo-ui/h5/source/style.cssare public;@varo-ui/h5/sourceis not a TypeScript entry. - Neutral behavior: import state/form contracts from
@varo-ui/headless;useBodyScrollLockbelongs to@varo-ui/h5/primitivesin H5 code only. Do not emulate DOM locking on native hosts. Form submit/failed handlers receiveSubmitPayload(FormSubmitPayloadin form source exports), containingvalues,errors, and optional platform-specificevent, not a raw DOM event. - Styles:
themes/basecontains tokens and foundation rules, not all component/Agent styles. Load the complete dependency CSS closure using the native global rule above; H5 installed source imports its dependency styles. - Agent installs: choose
components/agent-conversation,components/agent-workspace,components/agent-advanced, orcomponents/agent-ragas needed.components/agent-presentationowns pure shared types/helpers.blocks/agent-chatselects conversation dependencies, not advanced/RAG/fine-tuning UI;components/agent-uideliberately selects the full suite. Approval, network, retry, and cancellation execution policy remains application-owned. - Agent SDK: import
UIMessage/ AG-UI chunks from@tanstack/ai,ChatClientSnapshot/ChatClientfrom@tanstack/ai-client, and H5useChatfrom@tanstack/ai-vue. Varo provides no private protocol, stream controller, channel, SSE decoder, or event parser. Snapshot props take the actual SDK snapshot; static history usesAgentConversationMessage[].AgentPartStatus,AgentStreamStatus, andAgentToolPartlive in installedcomponents/agent-ui/typesand describe display only, not SDK states (ready,submitted,streaming,error). Renderer approval/rejection events carry interrupt IDs: the application resolves the matchingtool-approvalfromclient.getInterrupts()withtrue/false. Business authorization and execution remain application-owned. See the AI integration guide.
Input rejects edits while disabled or readonly. It notifies once when a value changes and sends no change event when the value stays the same. Cancel Drawer openChange synchronously in the handler to prevent the subsequent state change, model update, and close notification.
pnpm dev:playground-h5
pnpm --filter @varo/playground-weapp dev:aidev:ai prepares the WeChat DevTools project, starts the MCP HTTP service, and forwards DevTools console output and uncaught errors to the active terminal.
Native Blocks used only by blocks-lab are generated in apps/playground-weapp/src/blocks-lab/components/blocks/. Shared UI, Agent components, and helpers stay in the main source tree. pnpm sync:registry handles these paths and import changes; public Registry installations still use src/components/blocks/. The production build rejects a main package above 2 MiB or a synchronous reference to an unavailable sibling subpackage.
After native compilation, localize-native-components.mjs places subpackage-only component artifacts beside their consumers while keeping shared scripts and assets at their existing paths. CSS url(...) and quoted or URL-form @import references are decoded before resolving files and escaped when rebased, including CSS hexadecimal escapes, spaces, quotes, parentheses, and query/hash suffixes. External and data URLs retain their spelling. Missing dependencies and destination conflicts reject before any compiler output is changed; the production and exported-starter style verifiers use the same CSS reference parser.
pnpm run docs:devThis starts VitePress at http://localhost:5173 and prepares the native preview artifacts. The H5 and Mini Program tabs share device framing, example cases, language, and theme. Mini Program examples run compiled Wevu SFCs through glass-easel; their editable source remains available under View code. H5-only components retain explicit platform support boundaries.
For native slot context on WeChat, enable weapp.vue.template.nativeSlotContext: true and scopedSlotsRequireProps: true with default attached setup. Preview and headless observation limits are documented in the installation guide.
pnpm sync:registry
pnpm check:generated
pnpm check:architecture
pnpm typecheck
pnpm test
pnpm build
pnpm check:consumers
pnpm check:platformssync:registrygenerates files;check:generatedchecks for drift, including obsolete outputs inscripts/registry-projections.json, without writing. Sync deletes obsolete files only if their bytes match the recorded digest. If an obsolete output was edited, or a new output path conflicts with an authored file, that generator fails before writing. Authored renderers receiving style imports are never deleted. Preflight applies per generator, without a transaction across all three scripts or disk-failure rollback. Do not run writers concurrently or delete the inventory to bypass conflicts.check:architecturechecks imports between shared logic, runtime code, and tooling, rejecting old Vue-native renderer imports.- After generation and builds,
check:consumerschecks packed packages and fresh CLI installations in isolated projects: dependency/entrypoint isolation, H5/native compilation, complete source/style dependencies, minimal Agent Chat installs, and profile roundtrips with rejection of unsupported profiles. It does not run devices. check:platformsbuilds and checks seven native profiles. Usepnpm --filter @varo/platform-smoke build:alipayfor one platform;verify:alipaychecks existing artifacts.test:e2e:runnerchecks runner gates and native locator semantics.aria-hiddenexcludes nodes and descendants from role queries without hiding their pixels or blocking explicit XPath actions; visually hidden and disabled controls remain non-actionable.- Native custom-event listeners must preserve the declared event spelling, such as
@update:modelValue. Wevu normalizes colon events to lowercase with:replaced by-; adding a hyphen insidemodelValuechanges the event name and prevents the model update.
Native artifacts are in apps/platform-smoke/.generated/<profile>/dist/<compilerPlatform>, with application files in the nested dist/. Checks cover component references, templates and events, complete global styles, IDE paths, and Donut host metadata. To use open:<profile>, supply a registered AppID and vendor tools; missing prerequisites fail the command.
Realworld creates its manager with createAedPinia() in src/store/manager.ts. Install it before creating stores: call use(pinia) in native app.vue or createApp({}).use(manager) in local consumers. Through $subscribe, the plugin persists only the AED store in realworld-weapp-state format, including nested updates. Navigation data stays transient; disposing the store or manager releases subscriptions. Keep this configuration for persistence, rather than a setup-local deep watch or bare createPinia(). Local checks do not run wx.login, update checks, or device launch.
Use the Node and pnpm versions declared in the root package.json (engines and packageManager). Manifests and the lockfile record tooling versions.
Workspace test scripts explicitly select the shared root configuration and restrict discovery to the current package. The Weapp playground selects its native-SFC test configuration with jsdom; the standalone Realworld app uses its local configuration.
H5 uses vite-plugin-dts bundleTypes with an explicit @microsoft/api-extractor dependency so both published type entrypoints include their bundled private workspace types rather than referencing monorepo source paths.
See RELEASING.md for the repoctl, npm OIDC, and documentation deployment workflow.