Build and share plugins

A plugin is an npm package with a raea key: components your compositions import, and tools, panels and item types in the raea app, each sandboxed with only the permissions and hosts the person approved. Build one in a folder, test it with hot reload, and share it on npm or Git.

View as Markdown

A plugin adds to raea what it doesn't have yet. It's an ordinary npm package whose package.json has a "raea" key, and it can add to either side of raea, or to both:

The engine. Components, parts and systems your compositions import by the package's name, like any other package. raea looks for them in your plugins after the project's own packages, so a component installed once works in every project.
The app. A tool on feed items, a panel beside the feed, or a new kind of feed item that agents post. Each one is a React .tsx file that the app runs in a sandboxed frame of its own.

Plugins are installed per person. The app keeps them in ~/.raea/plugins (or RAEA_PLUGINS), and they're there in every project you open.

The manifest

JSON

{
  "name": "@you/raea-palette",
  "version": "0.1.0",
  "description": "Pull a palette from any still and pin it to the item.",
  "raea": {
    "title": "Palette",
    "raea": ">=0.1.0",
    "engine": { "imports": ["@you/raea-palette"] },
    "app": {
      "contributes": [
        { "point": "tool", "id": "palette", "title": "Palette", "entry": "./app/Palette.tsx", "on": ["look", "watch"] },
        { "point": "panel", "id": "swatches", "title": "Swatches", "entry": "./app/Swatches.tsx" },
        { "point": "item", "id": "board", "title": "Palette board", "entry": "./app/Board.tsx" }
      ],
      "permissions": ["items:read", "comments:write", "notify"],
      "network": ["api.example.com"]
    }
  }
}

key	what it says
`title`	the name the person sees on the Plugins page
`raea`	the raea versions it works with, as an npm range
`engine.imports`	what compositions import from it (the package's own `exports` are what actually resolve)
`app.contributes`	each part it adds to the app: `point` (`tool`, `panel` or `item`), an `id` of lowercase letters, digits and dashes, a `title`, and an `entry`, a `.tsx` inside the package
`on`	for a tool: the item types it shows on (`watch`, `look`, `listen`, `play`, `artifact`, `plugin`); every type when left out
`app.permissions`	what it may ask of the app beyond reading what it's shown on
`app.network`	the hosts its code may reach, exactly (`api.example.com`) or a subdomain wildcard (`*.example.com`); none when empty

A package without a "raea" key isn't a plugin, and the app refuses it at install, naming every problem it found.

Where a contribution shows

tool: a button in an item's detail view. Pressing it opens your component in a pane beside the item, and it gets the item it's on.
panel: a toggle on the feed that opens your component beside it, for the project as a whole.
item: a kind of feed item. An agent posts one with feed_post, type plugin, naming your plugin and the view, as "@you/raea-palette#board", and a JSON file that becomes the item's data. The feed shows the item with your component. If someone opens the item without your plugin, it says which plugin it needs.

Talking to the app: @raea/app

Your component is the .tsx file's default export. It imports react, @raea/app and its own files (.ts, .tsx, .js, .json), plus any packages it depends on. Tailwind classes work and use the app's own colours, so text-ink and bg-raised look right in both themes.

TSX

import { useState } from "react"
import { app, usePlugin, useItem } from "@raea/app"

export default function Palette() {
  const ctx = usePlugin()   // where it's shown: point, project, itemId, and an item's data
  const item = useItem()    // the item it's on: title, the agent's ask, its media with URLs (null in a panel)
  const [said, setSaid] = useState("")
  const pin = async () => {
    await app.comment("Palette: #1d2a3a #c58b4e #efe4d2")
    await app.notify("Pinned the palette")
    setSaid("pinned")
  }
  return (
    <main className="p-4 text-ink">
      <h1 className="text-sm font-medium">{item?.title}</h1>
      <button className="mt-3 rounded-md border border-line px-3 py-1.5 text-xs" onClick={pin}>Pin the palette</button>
      <p className="mt-2 text-xs text-ink-3">{said}</p>
    </main>
  )
}

call	needs	what it does
`app.context()` / `usePlugin()`	nothing	the plugin, the contribution, its point, the project, the item it's on, a plugin item's data
`app.item()` / `useItem()`	nothing	the item it's shown on, when there is one
`app.items()`	`items:read`	the project's feed items and their notes
`app.comment(text, pin?, itemId?)`	`comments:write`	a note on the item, optionally pinned to a place on it (0 to 1 across and down), or on another item by id
`app.notify(text)`	`notify`	a short notice for the person

A call without its permission is refused with an error that names the missing permission, for example "items needs the items:read permission, which this plugin wasn't given". A call that doesn't exist is refused and the error lists the calls that do.

What a plugin can't do

The frame is a sandbox. It has no access to the app's own code, your keys, the app's host or another plugin's frame. @raea/app is its only way to reach the app, and only fetch, XMLHttpRequest, WebSocket, EventSource and sendBeacon calls to the hosts in network get through. Anything else fails with an error that names the hosts the plugin may reach. Imports of Node's built-in modules (node:fs and the like) are refused, and so are files outside the plugin's folder.

Build and test it

Make a folder with the package.json above and your .tsx files.
In the raea app, open Plugins. Under Installed, type the folder's path (~/code/raea-palette) and press Install.
The plugin installs off. Its card shows what it adds, what it may do and which hosts it reaches. Press Approve and turn on.
Open an item and press your tool, or toggle your panel on the feed.
Edit the .tsx and save. A folder plugin is linked, not copied, so the app rebuilds it and the frame reloads in place. A compile error shows in the frame with its file and line.

To try an item view, ask your agent to post one: "post a palette board for this still with @you/raea-palette#board". It writes the JSON and posts it with feed_post.

Components for compositions

The same package can export components for the engine. Once the plugin is installed, any composition imports them by the package's name:

TSX

import { Grain } from "@you/raea-grain"

raea resolves an import from the project's own node_modules first, then from your plugins. A project that installs its own copy of a package keeps that copy. Components follow the rules every composition follows: every value comes from the frame, so a render matches a play. The SDK lists what they can import.

A plugin is shared the way any npm package is. Nobody uploads anything to raea.

npm: npm publish. People install it by typing its name (@you/raea-palette) on the Plugins page.
Git: push the folder to a repository. People install it with the Git URL (github:you/raea-palette or git+https://github.com/you/raea-palette.git).

Installing runs none of the package's code. npm's install scripts are off, and nothing in the plugin runs until the person has read its card and approved it. Turning a plugin off stops it everywhere without uninstalling it, and Remove uninstalls it. Neither touches a project's files.

Not built yet

raea add and raea app dev verbs for plugins.
Checking a plugin's raea range when it loads.
Rail tabs, commands, agent tools and settings pages as contribution points.
A browsable index of plugins with verified sources.

A native Bevy plugin (a Rust crate) still has to be in raea's catalog or built into raea from source. The Bevy plugin guide in the raea skill covers those.

#The manifest

#Where a contribution shows

#Talking to the app: @raea/app

#What a plugin can't do

#Build and test it

#Components for compositions

#Share it

#Not built yet