Developer
Browse topics
RobinPath Overview
On this page

Build an Applet

Applets extend RightPlace with new resource types, typed methods, and agent tools. Built in TypeScript, shipped as a signed bundle.

An applet is a self-contained TypeScript and React package that extends RightPlace with new functionality. It can own one or more resource types, expose typed methods, surface agent tools, and store data alongside the project it belongs to. Applets ship as signed bundles and install without a binary update.

This is the current SDK surface. The canonical contract lives in apps/rightplace-applet-sdk/API.md; these pages render it for builders.

What an applet is

Each applet declares its surface in a single applet.json manifest and implements it with the SDK builders from @rightplace/applet-sdk/v2:

import {
  defineApplet,
  defineMethod,
  defineEntity,
  defineEvent,
  defineCron,
  z,
} from "@rightplace/applet-sdk/v2";
  • Methods are typed operations (@author/slug.verb) callable from the UI, other applets, the CLI, and agents.
  • Entities are typed SQLite storage, one database per resource, stored in the project folder.
  • Events are typed pub/sub between applets.
  • Cron registers scheduled tasks.
  • Scopes declare every capability the applet uses; they are shown at install time.

How it runs

Signed first-party bundles run trusted-tier: native React performance, mounted in the host UI. Method bodies that need a backend run in a Node sidecar (runtime: "sidecar"). Unsigned and community bundles run in an iframe sandbox.

Data is project-tier by default. Each resource gets its own SQLite database at {projectFolder}/{resource folderPath}/{filename} (default data.db), so it syncs with the project rather than the user’s app cache.

The shape of a bundle

my-applet/
  bundle.json          # release wrapper: id, version, publisher, sdkVersion, applets[]
  applet.json          # per-applet manifest: id, scopes, methods, tools, frontend.entry
  manifest.sig         # detached Ed25519 signature over bundle.json bytes
  src/
    index.ts           # defineApplet({ id, methods, entities, events, render })
    index.node.ts      # sidecar entry: registerMethods(ctx)
    mount.tsx          # React root
    methods/           # defineMethod definitions
    entities.ts        # defineEntity definitions
    events.ts          # defineEvent definitions
  skills/              # markdown skills that teach agents how to use the methods
  dist/                # vite output: index.js, index.node.js, public.d.ts, validators/*.js

Where to go next