Mini-Program SDK Development for Third-Party Developers
A mini-program SDK is your ecosystem's public contract. Once deployed to production, you commit to maintaining backward compatibility for years. WeChat learned this painfully in 2019 when a breaking change to the core <scroll-view> component broke hundreds of thousands of mini-programs. Therefore, SDK design is first and foremost API boundary design.
What's Included in an SDK for Third-Party Developers
An SDK is not a single library. It's an ecosystem of tools:
- Runtime JS library — linked inside a mini-program, provides APIs (geolocation, payments, camera, network via bridge)
- CLI tool — build, preview, publish to marketplace
- Local simulator — run mini-program on desktop without real Super App
- TypeScript definitions — without them IDE can't suggest, and developers typo method names
- Documentation with interactive examples
The first mistake we see in team audits: they start with the runtime library and forget CLI and simulator. External developers end up uploading each version to the real Super App for testing. Onboarding becomes a nightmare, ecosystem stalls.
Runtime API Design
The SDK's core is a JavaScript library running inside a mini-program's WebView. It provides abstraction over the container's bridge protocol.
Structure of a typical call:
// Bad — direct bridge call
window.__miniapp_bridge__.call('camera.take', {quality: 0.8}, callback)
// Good — through SDK
import { camera } from '@superapp/sdk'
const result = await camera.take({ quality: 0.8 })
The SDK handles: correlation IDs for async calls, timeout handling, error normalization to standard {code, message, data} format, polyfills for iOS/Android bridge differences. This is critical: if Android returns coordinates with 6 decimal places and iOS with 8, developers get incompatible results across platforms.
Version API through capability detection, not version strings:
if (sdk.supports('payment.applePay')) {
// iOS 16+, select regions only
} else {
sdk.payment.card()
}
CLI: Build and Publish
The CLI is the entry point for most developers. It must work out of the box without a three-page setup guide.
Typical workflow:
superapp init my-miniapp --template=react
cd my-miniapp
superapp dev # hot-reload local simulator
superapp build # production bundle with tree-shaking
superapp publish # upload to marketplace, create review request
Under the hood, the bundler is Webpack 5 or Vite with custom plugins: tree-shake unused native APIs (if the mini-program doesn't use Bluetooth, it stays out of the bundle), parse manifest permissions and warn about undeclared calls, minify and code-split for faster WebView cold start.
Bundle size is painful. WebView inside mini-programs doesn't cache resources like a browser. Each launch downloads the bundle. Goal: main bundle < 200 KB gzipped. Anything heavier uses lazy chunks via dynamic import().
Local Simulator
The simulator is a desktop application (Electron or native) emulating the Super App's runtime container on a developer's local machine. It implements the same bridge API as the real container, but with devtools: bridge call inspector, mock geolocation and camera data, network throttling, screen size simulation.
In practice, the simulator gives 90% coverage for development. The remaining 10% is specific WebView behavior on actual devices. For those, we support remote debug mode: the simulator relays bridge calls to a real device via USB/ADB.
TypeScript Definitions and Developer Experience
An SDK without types in 2024 is an antipattern. Developers use TypeScript, and IDE hints directly impact development speed and bug counts.
Generate definitions from a single source of truth — a JSON Schema API manifest. This guarantees sync between documentation, runtime behavior, and types. Monorepo SDK: packages/types, packages/runtime, packages/cli, packages/simulator — with shared schema in packages/schema.
Backward Compatibility and Deprecation Policy
This is the most underrated part. Once the SDK is in production with external developers, every breaking change requires a migration guide and 6-month deprecation window minimum.
What helps:
- Semantic versioning with clear rules (patch — bugs only, minor — new APIs, major — breaking changes)
-
@deprecatedannotations in TypeScript with JSDoc describing alternatives - Runtime warnings when deprecated APIs are used (can disable in prod)
- Changelog with migration examples for each major version
Development timeline for complete SDK (runtime + CLI + simulator + types) from scratch: 4 to 8 months. Runtime library only against existing bridge: 6 to 12 weeks.