> For the complete documentation index, see [llms.txt](https://basedapp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://basedapp.gitbook.io/docs/integrations/mini-apps-platform/01-overview.md). # Goals & non-goals ## What we're building A **mini-app platform** embedded in the Based Super App. Third-party and first-party developers ship a JavaScript bundle plus a manifest. The Based host app loads the bundle into a sandboxed JS runtime, exposes a curated set of native capabilities through a `based.*` API, and renders the mini-app's UI declarations using the host's native Flutter widgets. The closest analog is **WeChat Mini-Programs**: same goals (extensibility without binary growth, partner ecosystem, hot updates, sandboxed execution), adapted for Flutter and the crypto/finance domain. ## Goals | # | Goal | Why it matters | | -- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | G1 | **Sandboxed execution** — partner code cannot reach native APIs, file system, or other mini-apps directly. | Lets us host third-party code without a per-partner audit of every release. | | G2 | **Hot-updatable** — mini-apps update without an App Store / Play Store release. | Partners ship at their own pace; we ship at ours. | | G3 | **Stable, versioned API contract** — `based.*` surface is semver'd and explicitly opted into via manifest. | Lets the host evolve internals freely while keeping mini-apps compatible. | | G4 | **Native rendering quality** — mini-app UIs use the same widget library as first-party screens. | No "obviously embedded webview" feel; consistent theming across tenants. | | G5 | **App Store compliant** — passes Apple guideline 4.7 and Google equivalents. | Without this, the platform cannot ship. | | G6 | **First-class crypto primitives** — signing, wallet selection, chain switching, balance reads exposed safely. | This is what differentiates us from generic mini-app platforms. | | G7 | **Based-tenant only** — the mini-app surface is gated to the Based tenant. Hyena and future tenants do not host mini-apps. | Scoping the platform reduces blast radius and review surface. The host still inherits tenant-aware theming for the Based theme variants (dark/light, etc.). | ## Non-goals These are explicitly **not** what we're building, at least not in v1: * **A general-purpose JS app platform.** Mini-apps are scoped to the host's domain (crypto, finance, commerce). We don't aim to compete with React Native or Capacitor. * **A native code extension surface.** Mini-apps cannot ship native code in v1. (Maybe later, gated to first-party.) * **Webview-based execution.** No `WebView`. The runtime is JS-only against a Dart-rendered widget tree. * **Compile-time modularity.** Internal feature teams may still use compile-time melos modules; the mini-app platform is an *additional* path, not a replacement. * **Multi-tenant hosting.** The Hyena tenant (or any future tenant) does not host mini-apps. The platform is Based-only by decision, gated at runtime via `tenantId == "based"`. * **A reactive framework as expressive as React Native.** UI is intentionally constrained to a curated widget set. Partners trade flexibility for consistency, security, and updateability. ## Success metrics (target: 12 months post-launch) | Metric | Target | | --------------------------------------------------- | ------------------------------ | | Number of live mini-apps | 10+ (mix of 1st and 3rd party) | | Median time from partner code change → user-visible | < 1 hour | | P95 mini-app cold start (bundle already cached) | < 800 ms | | P95 mini-app cold start (bundle uncached) | < 3 s on 4G | | Sandbox escape incidents | 0 | | Host crashes attributable to mini-apps | < 0.01% of host sessions | ## Target users There are three distinct audiences for this platform; the design must serve all three. | Audience | What they need from us | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | **Internal feature teams** (e.g., the team that built `shop`) | Faster release cadence, ability to iterate without app review, parity with native widget library. | | **Trusted partners** (DEXs, yield protocols, NFT marketplaces) | Stable API, predictable theme inheritance, signing flows that don't leak keys, simple distribution. | | **Long-tail third parties** (eventually) | Self-service docs, simulator, sandbox to develop in, clear permission model so users trust their mini-app. | The first two are the v1 audience. Long-tail self-service is a v2 concern. ## WeChat parallels and divergences We borrow heavily from WeChat's model. Where we diverge, it is deliberate. | WeChat | Based mini-apps | Note | | ----------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------- | | WXML/WXSS DSL | TypeScript / JS calling `based.ui.*` builders | We don't want to invent a markup language; the widget catalog is the constraint. | | `wx.*` global | `based.*` global | Same idea: a curated, manifest-gated surface. | | `app.json` | `based.json` | Same idea; different schema. | | Hosted in WeChat super-app | Hosted in Based super-app | Same. | | Server-rendered + client logic | Pure client-side | We don't need WeChat's scale of server-driven state. | | Native components (``) | Native widget catalog (`AppButton`, `AmountInput`, ...) | Aligned with `based_ui`. | ## High-level system diagram ```mermaid flowchart TB subgraph host["Based Host App (flutter/based_app)"] FP["First-party screens
(trade, predict, shop)"] UI["based_ui widget library
(AppButton, AppCard…)"] CORE["based_core
(auth, signing, http,
storage, nav, theme)"] subgraph container["Mini-App Container"] REND["UiNodeRenderer
(renders based_ui)"] JS["JS Runtime (QuickJS)
main.js (partner code)
based.* API"] HOSTIF["BasedMiniAppHost
(permission-checked)"] JS -- "UiNode tree" --> REND HOSTIF -- "Dart↔JS bridge" --> JS end FP --> UI HOSTIF --> CORE end CDN["Mini-App CDN
(signed bundles, versioned)"] host -- "fetch bundle + manifest" --> CDN ``` Each layer is detailed in the documents that follow. Architecture is in `02-architecture.md`. ## Key design principles These principles are appealed to throughout the rest of the docs. When two designs conflict, the one more aligned with these principles wins. 1. **Sandbox by default, capability on request.** Mini-apps get nothing until the manifest declares it and the user (transitively) approves it. 2. **The host owns user trust.** Every signing, payment, or sensitive action is mediated by a host-controlled UI sheet — never rendered by mini-app code. 3. **Native rendering, declarative input.** Mini-apps describe what they want; the host decides how to render. This keeps the visual surface consistent and the attack surface small. 4. **Versioned, narrow API.** Every `based.*` method is versioned and minimal. We add slowly; we never silently break. 5. **Boring runtime.** QuickJS, JSON over a message channel, no exotic threading. Optimize the boring case. 6. **One bundle, one mini-app.** No dynamic module loading at runtime. Updates ship as new bundles. Read [`02-architecture.md`](/docs/integrations/mini-apps-platform/02-architecture.md) next.