Quickstart

Create a capability-free React and TypeScript miniapp with the public initializer. The generated project includes a desktop surface, package descriptor, Module Federation build, package assembly, portability check, and Test Lab scaffold.

Prerequisites

  • Node.js 20 or later
  • pnpm 10.33.1 or later
  • A supported installation of The AI Platform

Create the Project

pnpm create tap-miniapp hello-miniapp

The initializer generates globally unique package, publisher, and organization IDs. It also derives the namespace, slug, display name, remote name, and contribution ID from the project directory. It shows the identities before writing anything. The destination must be new or empty, and a failed initialization leaves it unchanged.

The generated IDs live in tap-miniapp.config.ts. Keep them stable after you publish or install the miniapp. When you create another miniapp for the same publisher or organization, reuse its existing identity with --publisher-id or --organization-id. Use --package-id only when recreating a project that already has a permanent package identity.

By default, the initializer installs exact dependencies and runs the generated Test Lab scaffold check, doctor, TypeScript checks, build, package assembly, and portability check.

Run It from an Agent or CI

Every prompt has a flag. Use the non-interactive contract when an agent or automation creates the project:

pnpm create tap-miniapp hello-miniapp \
  --non-interactive \
  --json

--json emits one machine-readable success or failure result and implies --non-interactive. The success result includes the generated packageId, publisherId, and organizationId. Use --no-install only when another step owns dependency installation and project checks. Run pnpm create tap-miniapp --help for identity and deterministic presentation overrides.

Understand the Generated Contract

The generated package.json pins pnpm and defines one canonical package build:

package.json
{
  "packageManager": "pnpm@10.33.1",
  "tapMiniapp": {
    "output": "dist"
  },
  "scripts": {
    "dev": "tap-miniapp dev",
    "build:target": "rslib build",
    "build:miniapp": "tap-miniapp build",
    "build": "pnpm run build:miniapp"
  }
}

tap-miniapp build reads the typed authoring config, runs every declared target builder, assembles the package, and verifies the portable output. tapMiniapp.output names the directory that The AI Platform should follow. The developer command reads both instead of guessing a framework or output path.

The starter declares one workspace-left surface with no platform capabilities. Add storage, network, channels, specialists, workflows, or other host APIs only when the product needs them, then declare the corresponding permission actions in tap-miniapp.config.ts.

Add a specialist

Create a package-owned specialist without editing the descriptor or calculating its versioned asset path:

pnpm exec tap-miniapp create specialist \
  --id query-expert \
  --display-name "Query Expert" \
  --purpose "Analyze query results and explain the important details." \
  --tags database,analysis \
  --non-interactive \
  --json

The command adds a host-declarative specialist contribution and creates the versionless source file specialists/query-expert.json. The build compiler writes its release-versioned package asset. It selects the package's declared desktop and mobile targets by default. Pass --targets desktop, --targets mobile, or both when the specialist should be available on fewer targets.

Every tap-miniapp create command is non-interactive. --non-interactive makes that contract explicit for an agent, while --json emits one result object and implies it. Existing contribution IDs and files are never overwritten.

Add a chat block

Give the specialist a structured block that renders in the conversation transcript:

pnpm exec tap-miniapp create chat-block \
  --id query-report \
  --specialist query-expert \
  --primitive report \
  --accessibility-label "Query report" \
  --fallback-format markdown \
  --non-interactive \
  --json

The command adds a chat.block contribution, creates schemas/chat-blocks/query-report.json, and updates the selected specialist's prompt with the exact draft envelope. The --specialist flag is an authoring instruction. It does not invent a stored ownership field in the package descriptor.

Choose table, report, or notice. These are the executable tap-primitives-v1 renderers currently provided by the host. The specialist emits package_chat_block_draft; The AI Platform validates its active package release and JSON Schema, then seals provenance before the block is stored. The generated prompt also requires a complete text fallback for clients that cannot render the block.

Run pnpm exec tap-miniapp --help for every deterministic override.

Start Development

cd hello-miniapp
pnpm dev

The command builds immediately, then watches the project and coalesces changes into complete package generations. A failed build leaves the previous successful output available and keeps watching.

For a one-shot agent check, run:

pnpm exec tap-miniapp dev --once --json

Use --root <path> when the miniapp project is not the current directory. JSON mode emits newline-delimited lifecycle, build, diagnostic, and generation-ready events so an agent does not need to parse terminal prose.

  1. Open Settings > Miniapps in The AI Platform.
  2. Add a Local Directory source.
  3. Select the generated hello-miniapp/dist directory.
  4. Open the miniapp from the workspace navigation.

The AI Platform watches every linked local directory automatically. There is no host-side watch switch and no reinstall step after a successful build.

Family Task Board miniapp open in The AI Platform with child and chore management forms.
A linked local package renders inside its declared platform surface while the developer command rebuilds complete generations.

The installation reports Refreshing, Active, Review required, Failed, or Path unavailable. A broken generation never replaces the active one.

Permission removals and narrower authority activate automatically. New, broader, or incomparable authority requires review before activation. Changes to local service contributions also require review. This keeps the local package mutable without silently expanding what it can do.

Next Steps