How Uni API Enables True Write‑Once, Run‑Everywhere for Mini‑Apps

As major mobile app vendors launch their own mini‑program solutions, developers face the challenge of supporting multiple platforms with a single codebase. While cross‑platform frameworks such as Rax, uniapp, Taro, and Remax address UI reuse, there is no standard for the underlying API layer, leading to fragmented and cumbersome code.

Uni API’s Birth

At Alibaba, after a series of evolutions—Hybrid, Native integration, dynamic templates, mini‑programs, and progressive web rendering—cross‑platform demands grew rapidly. Developers spent excessive effort adapting APIs for each container. The surge of community group‑buying mini‑programs highlighted the need for a true "one code, multiple ends" solution, prompting the creation of Uni API.

What Is Uni API?

Supports Web, WeChat Mini‑Program, ByteDance Mini‑Program, Alibaba Mini‑Program, Baidu Mini‑Program, and Kuaishou Mini‑Program.

Framework‑agnostic; can be used in any native or cross‑platform project.

Bilingual documentation with abundant examples.

Implements 101 common APIs, with on‑demand loading and environment‑based tree‑shaking.

Provides complete TypeScript declarations for seamless IDE assistance.

Problems Uni API Solves

Inconsistent API prefixes (e.g.,

tt.

,

wx.

) and call patterns across containers.

Divergent input/output specifications.

Lack of TypeScript declarations in native APIs.

Developers must consult multiple docs and write compatibility layers, inflating code size.

Missing Web implementations hinder browser debugging.

Specification

API Classification

APIs identical across containers (same parameters, behavior).

APIs with differences that can be normalized transparently.

APIs with differences that cannot be fully unified.

Container‑specific exclusive APIs.

Uni API handles each class accordingly: removing prefixes or promisifying for class 1, normalizing parameters for class 2, exposing subset capabilities for class 3, and omitting class 4 from the common set.

Input Specification

Differences are addressed via an

_ext

field. Example:

<code>import showActionSheet from '@uni/action-sheet';
showActionSheet({
  itemList: ['A', 'B', 'C'],
  _ext: {
    aliMiniApp: { title: 'Extra title for Alipay' },
    wechatMiniProgram: { itemColor: '#ff1214' }
  }
}).then(res => {
  console.log(`Selected index: ${res.tapIndex}`);
});</code>

Only the relevant parameters are applied in the corresponding container.

Output Specification

Uni API normalizes return values, exposing a common subset while preserving container‑specific fields for developers to use as needed.

Core Capabilities

True write‑once, run‑everywhere: Automatic environment detection and compatibility handling free developers to focus on business logic.

No framework dependency: Works in any native mini‑program or cross‑platform project; Web side uses plain DOM.

More ergonomic API: Logical grouping of related APIs and Promise‑based async handling improve code readability.

Comprehensive coverage: Over 100 APIs planned, with 70+ implemented in the first release, covering >80% of typical scenarios.

Extreme efficiency: Atomic API design and tree‑shaking keep bundle size minimal, matching native call overhead.

Supporting Capabilities

Bilingual documentation: Detailed Chinese and English docs for each API and parameter, reducing the need to consult multiple vendor docs.

Real‑device demos: QR‑code‑linked demos allow instant testing on all supported platforms.

Full TypeScript declarations: Enables IDE auto‑completion and static type checking, preventing common mistakes.

CanIUse tool: Runtime API support detection, e.g.

import canIUse from '@uni/caniuse';
canIUse('clipboard'); // true

.

How to Use Uni API

Installation

Two import modes are provided:

Small package

<code>npm install --save @uni/storage
import { getStorageSync } from '@uni/storage'
getStorageSync({key: 'key'})</code>

Full package

<code>npm install --save @uni/apis
import { application, env, storage } from '@uni/apis'
confirm({content: 'Show modal'})
storage.getStorageSync({key: 'key'})</code>

Build Plugins

Use the Babel plugin to strip unused APIs:

<code>npm i @uni/babel-plugin-universal-api-import</code>

<code>[
  'babel-plugin-universal-api-import',
  { target: 'miniapp' }
]</code>

Rax users can add the Rax‑specific plugin:

<code>npm i @uni/build-plugin-rax-api-import</code>

<code>{
  "plugins": [
    ["build-plugin-rax-api-import"]
  ]
}</code>

Design Scheme

Uni API develops each API atomically across six container dimensions, currently delivering 65 APIs × 6 containers = 390 implementations. Future plans target 101 APIs across six containers, reaching over 600 modules and 50+ packages.

Conclusion

Uni API bridges the gap between disparate mini‑program containers and the web by providing a unified, lightweight, and type‑safe API layer. It aims to support more containers and expand its API catalog while maintaining minimal bundle size and optimal developer experience.

Related Links

Official site: https://universal-api.js.org/

Rax site: https://rax.js.org/

GitHub: https://github.com/raxjs/universal-api

Issues: https://github.com/raxjs/universal-api/issues