The AI Platform Miniapp SDK

@theaiplatform/miniapp-sdk is the public package for building portable miniapps that run in The AI Platform.

pnpm add @theaiplatform/miniapp-sdk

The package provides the host-injected SDK API, isolated surface lifecycle types, browser helpers, portable React UI components, manifest schema, and the Rspack/Rslib integration used to produce descriptor-backed Module Federation targets.

Start with the Miniapp SDK documentation.

Supported entry points

• @theaiplatform/miniapp-sdk
• @theaiplatform/miniapp-sdk/sdk
• @theaiplatform/miniapp-sdk/web
• @theaiplatform/miniapp-sdk/ui
• @theaiplatform/miniapp-sdk/ui/wasm
• @theaiplatform/miniapp-sdk/ui/styles.css
• @theaiplatform/miniapp-sdk/ui/tailwind.css
• @theaiplatform/miniapp-sdk/ui-components.json
• @theaiplatform/miniapp-sdk/surface
• @theaiplatform/miniapp-sdk/config
• @theaiplatform/miniapp-sdk/rspack
• @theaiplatform/miniapp-sdk/config-schema.json

The host API is injected at runtime. Importing an entry point is safe in build tools and tests; host-backed calls fail when used outside a supported runtime. sdk.storage provides revisioned non-secret JSON scoped by the host to the active workspace and exact package. sdk.presence provides host-stamped, ephemeral room membership and state; package code never supplies participant identity. On supported desktop surfaces, sdk.http sends bounded HTTP(S) requests through host consent instead of browser fetch, and sdk.credentials lists metadata-only HTTP credential references. Credential secrets remain in the host vault and are injected only by the native request authority.

sdk.printing is an optional desktop-only receipt printer API. It discovers bounded machine-local printer metadata and host-supported 58 mm and 80 mm paper profiles, then accepts only bounded semantic version-1 receipt rows with printable ASCII text and a stable job key. The miniapp passes its exact printer/profile selection to status and submission; the host revalidates that destination and owns wrapping, feed, cut, and OS spooler submission. Packages must declare the exact descriptor effect { "kind": "physical-output", "resources": ["receipt-printer"] } and a persisted printing.receipt action with reusable consent, do autonomy, and consequential risk. Raw ESC/POS, direct USB/network access, and window.print() are not SDK capabilities. Job-key journaling suppresses routine reconnect duplicates, but physical exactly-once printing is impossible; every result therefore carries physicalExactlyOnce: false.

Discovery metadata

Descriptor-backed packages may assign up to three unique presentation.categories. Import the MiniAppCategory type from the package root or /config; accepted values are productivity, developer-tools, creativity, communication, data-and-analytics, business, education, media-and-entertainment, utilities, and other.

Do not add an authored includes field. The host derives the package's stable, counted capability summary from its verified contributions, so Marketplace details cannot drift from the code the descriptor is allowed to expose.

Portable UI

Import the precompiled stylesheet once at the miniapp entry point, then use components from the public UI entry. React 19 is a peer dependency.

import '@theaiplatform/miniapp-sdk/ui/styles.css';

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
} from '@theaiplatform/miniapp-sdk/ui';

export function WelcomeCard() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Ready to build</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Continue</Button>
      </CardContent>
    </Card>
  );
}

Tailwind v4 miniapps can instead import the source integration after tailwindcss and tw-animate-css; it supplies the platform theme and scans the SDK's UI bundle for component classes.

@import 'tailwindcss' source(none);
@import 'tw-animate-css';
@import '@theaiplatform/miniapp-sdk/ui/tailwind.css';

@source './src';

Use installMiniAppAppearanceSync() from the /web entry to apply the host's light/dark theme and bounded UI scale. Tools and agents can read the exported ui-components.json catalog to discover the supported component families and style entry points without importing application-private packages.

Rust/WASM UI

Rust/WASM miniapps can render the same public component library through the imperative /ui/wasm entry. It accepts a bounded serializable model, owns its React root and providers, and emits serializable actions with stable control IDs, entity IDs, model revisions, and unique event IDs.

import '@theaiplatform/miniapp-sdk/ui/styles.css';
import { createMiniAppUiRoot } from '@theaiplatform/miniapp-sdk/ui/wasm';

const ui = createMiniAppUiRoot(element, model, (action) => {
  wasm.onUiAction(action);
});

ui.update(nextModel);
ui.focus('project-name');
ui.unmount();

The bridge synchronizes theme and UI scale, restores focus for controlled dialogs, exposes a live-announcement method, rejects malformed or stale models, reports render and dispatch failures explicitly, and makes teardown idempotent. See examples/wasm-ui for a clean wasm-bindgen consumer that maps JavaScript exceptions to Rust Result values and rejects stale or replayed actions.

License and public policies

By downloading, installing, copying, accessing, or using this SDK, you accept the Miniapp SDK Proprietary License Agreement. The SDK has no separate license fee and is provided as-is under that agreement.

• Acceptable Use Policy
• Privacy Notice
• Security and Responsible Disclosure Policy
• Developer and Marketplace Policy
• Third-Party Notices