Publishing a Plugin

This guide shows how to publish a community plugin so it appears in Composer’s plugin registry. It assumes you already have a working plugin — if you don’t, start with the Plugin Tutorial and use plugin-excalidraw as a reference implementation.

How the registry works

The DXOS registry is AT Protocol-native. You don’t submit your plugin to a central database — instead, you publish records to your own AT Protocol repository (your PDS), and the DXOS registry indexes them:

You publish a small set of org.dxos.experimental.* records (a publisher profile, a package profile, and one release per version) to your PDS using the dx CLI.
The registry’s indexer ingests those records from the AT Protocol firehose and serves them to Composer.
Composer lists your plugin in its registry and loads the bundle on demand.

Because the records live in your own repo, you remain in control of them — updating or removing a plugin is just a record write or delete on your side.

Discovery is gated by verification. The indexer only surfaces plugins from publishers that DXOS has vouched for. This keeps the registry curated. You request verification once (see Get verified); after that you can publish and update plugins freely.

Prerequisites

A built Composer plugin with a dx.config.ts (see Describe your plugin).
A DXOS identity with a connected AT Protocol account (e.g. a Bluesky handle) — the same identity you use in Composer. Or, for headless use, an AT Protocol handle and an app password.
The DXOS CLI.

1. Install the CLI

npm install -g @dxos/cli
dx --version

2. Authenticate

A Composer account is required in both cases below — publishing writes to your AT Protocol repo and uploads your bundle to DXOS-hosted storage, both of which are tied to a DXOS identity. The two options differ only in how you supply your AT Protocol credentials.

Option A — Log in (recommended)

If your Composer account has a connected AT Protocol account (Bluesky), log in:

dx account login

login prompts for a method, mirroring Composer’s sign-in: atmosphere (your Atmosphere account, i.e. Bluesky), email, device-invitation, or recovery-code. You can also pass them directly, e.g. dx account login --method atmosphere alice.bsky.social.

Once logged in, dx registry commands sign your PDS writes through DXOS edge using the AT Protocol account connected to your identity — no app password needed. If you signed up for Composer with Bluesky it’s already connected; otherwise connect one with dx integration add (or from Composer’s settings). Log out with dx account logout.

dx account login signs in to an existing identity — it doesn’t create one. Create your identity in Composer, or run dx account signup <access-code> if you have an access code (it takes the same --method atmosphere / --method email choice).

Option B — App password

If your Composer account does not have a connected AT Protocol account, supply your AT Protocol credentials directly via an app password (not your account password — create one at bsky.app/settings/app-passwords):

dx account login  # log in to your Composer account first
export ATPROTO_HANDLE=alice.bsky.social
export ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

Every dx registry command also accepts --handle and --app-password explicitly. Explicit credentials take precedence over the connected AT Protocol account on your identity.

3. Get verified

So that your plugin is discoverable, ask the DXOS team to verify your publisher identity. Reach out on the DXOS Discord (or by email if you have a contact) with:

Your AT Protocol handle (or DID).
A short description of the plugin(s) you intend to publish.

A DXOS verifier attests to your identity by writing a verification record for your DID. You only need to do this once — subsequent plugins and version updates from the same identity are picked up automatically.

You can publish your records before being verified; they simply won’t appear in Composer until verification is in place.

4. Publish your publisher profile

Publish the profile that represents you (or your organization) in the registry:

dx registry publish-publisher \
  --display-name "Alice" \
  --bio "Building diagramming tools for Composer." \
  --homepage-url https://example.com \
  --contact alice@example.com

Only --display-name is required; the rest are optional.

5. Describe your plugin in `dx.config.ts`

dx.config.ts at the root of your plugin package is the single source of truth for your plugin’s registry metadata. The build reads it to emit the manifest, and dx registry publish reads that manifest to write your records.

import { Config2 } from '@dxos/app-framework/config';

export default Config2.make({
  plugin: {
    key: 'org.dxos.plugin.excalidraw', // required — a reverse-domain NSID; the plugin's globally-unique key
    name: 'Excalidraw', // required
    description: 'Professional diagramming powered by Excalidraw.',
    icon: { key: 'ph--compass-tool--regular', hue: 'indigo' },
    source: 'https://github.com/your-org/your-plugin',
    tags: ['labs'],
    screenshots: [
      {
        light: 'https://example.com/screenshot-light.png',
        dark: 'https://example.com/screenshot-dark.png',
      },
    ],
  },
  publish: {
    buildCommand: 'vite build', // how to build the bundle
    outputDirectory: 'dist', // where the build emits manifest.json
  },
});

Import Config2 from @dxos/app-framework/config, not from @dxos/app-framework. The /config subpath is a lightweight entry point with no heavy transitive dependencies — the main entry pulls in the full UI framework which is not needed at build/publish time.

Field reference for plugin:

Field	Required	Notes
`key`	yes	Reverse-domain NSID (e.g. `org.dxos.plugin.excalidraw`) whose last segment is camelCase — no hyphens. The plugin’s globally-unique key.
`name`	yes	Human-readable name shown in the registry.
`description`	no	Short description shown on the plugin’s detail view.
`author`	no	Author or organization name.
`icon`	no	`{ key, hue? }` — a Phosphor icon name and optional display hue, e.g. `indigo`.
`source`	no	Source repository URL.
`homePage`	no	Homepage URL.
`tags`	no	List of tags for categorization/discovery.
`screenshots`	no	Preview images for the plugin’s detail view. Each entry is a `{ light?, dark? }` record of theme-specific URLs.

Field reference for publish:

Field	Required	Notes
`buildCommand`	no	Build command run by `dx registry publish` (skipped with `--no-build`).
`outputDirectory`	no	Directory the build emits into (must contain `manifest.json`). Defaults to `dist`.
`assetBaseUrl`	no	Skip the upload and point the release at a bundle you host yourself.

The release version is taken from your package.json version field, not from dx.config.ts. Bump it before publishing a new release.

Wire composerPlugin into your vite.config.ts so the build emits the manifest:

import { composerPlugin } from '@dxos/app-framework/vite-plugin';

export default defineConfig({
  plugins: [
    ...composerPlugin({ entry: 'src/MyPlugin.tsx' }),
    // ...react(), etc.
  ],
});

Pin every @dxos/* dependency to the same version the Composer host runs, and bump them in lockstep. A plugin built against mismatched framework versions can fail to load.

6. Publish

From your plugin directory:

dx registry publish

This will:

Run your build.command (skip with --no-build to publish a pre-built dist).
Read the emitted manifest.json.
Upload the bundle to the DXOS edge and record the resulting moduleUrl.
Write a package.profile record and a package.release record (rkey <key>:<version>) to your PDS.

Useful flags:

Flag	Purpose
`--dir <path>`	Project directory containing `dx.config.ts` (defaults to the current directory).
`--no-build`	Skip the build and publish the existing `dist`.
`--asset-base-url <url>`	Skip the upload and point the release at a bundle you host yourself.
`--edge-url <url>`	Override the edge used for upload (mainly for local testing against a dev worker).
`--private`	Publish privately instead; see below.

Publishing privately

dx registry publish --private skips AT Protocol altogether: no PDS session, no verification, no records. The bundle is hosted the same way, but the registry records it against your DXOS identity, and it is listed in Composer’s registry only to you. The first release of a key claims it, so no other identity can publish that key privately afterwards.

It authenticates as the identity you logged in with (dx account login). A process that has no identity of its own, such as a CLI in a sandbox or a CI job, authenticates with an API token in DX_API_TOKEN instead: the token is bound to the account that minted it, so the plugin is listed to that account. In Composer, a sandbox gets one from its Grant account access action, which mints a token that expires with the sandbox.

7. Confirm it’s published

List the records now on your repo:

dx registry records

You should see your publisher.profile, the package.profile, and a package.release. Once your identity is verified, the plugin appears in Composer’s registry within a few minutes (the indexer refreshes periodically). Open Composer’s plugin registry and look for your plugin.

Updating a plugin

Bump the version in package.json, then run dx registry publish again. Each version is published once — the hosted bundle for a version is immutable (re-publishing an existing version is rejected), so bump the version to ship changes. Users can install the latest.

Removing a plugin

dx registry unpublish --key org.dxos.plugin.excalidraw

This removes the package profile and all of its release records from your PDS. The registry stops listing it on the next refresh.

Local development

You don’t need to publish to test your plugin against Composer. Composer loads a plugin from the URL of its manifest.json, so anything that serves a manifest and the entry module it names can be loaded. There are two ways to do it.

From your plugin’s dev server

This is the loop to use while you work on a plugin. Run Vite’s dev server in your plugin’s directory:

vite

composerPlugin binds it to port 3967 and serves a dev manifest at http://localhost:3967/manifest.json, which points at your unbundled source. If the port is taken, Vite fails rather than moving to another one, since Composer loads from 3967.

In Composer, click Plugin Settings in the rail and open Plugins. Under Dev Server, the Manifest URL defaults to http://localhost:3967/manifest.json; change it only if you passed another port to composerPlugin. Click Enable. Composer loads the plugin and enables it in one step.

It reloads with the app. Dev Server stays on until you click Disable, and every reload of Composer loads your plugin again from the dev server, so an edit is one reload away. React fast refresh does not reach a plugin served from another origin, so reload the app rather than waiting for a hot update.
It is never installed. A dev plugin is not saved in your profile or in the offline cache. If the dev server is down at boot, Composer logs a warning, shows it under Dev Server, and tries again on the next reload.
It can stand in for an installed plugin. When your dx.config.ts key matches a plugin you already have, from the registry or built in, the dev plugin takes its place for the session. Disable restores the original.

From a built bundle

Build the plugin (see the example) and serve its dist directory, which contains manifest.json and index.mjs, with CORS if it is on another origin. In Composer, open Plugins, click Load from URL (the cloud icon in the Plugins header) and paste the manifest URL. Unlike a dev plugin, a plugin loaded this way is installed: it stays in your profile and its files are cached for offline use.

The URL must point at the manifest, not at a source file: the loader fetches the manifest first and imports the entry it names.

With an assistant

To have the assistant build one for you, create a project from the Composer Plugin template in the Composer desktop app, with the Sandbox plugin on. Its parent task and four subtasks walk a chat through the example below in a sandbox on your computer, from fetching this guide to the load prompt; assign them to the agent to start it.

In a browser, the template comes from the Coding (Dev) plugin and needs a Composer served locally by vite preview. There the chat writes the files and checks them against the plugin’s dev server. The assistant cannot keep a dev server running, so start it yourself once the chat asks, from the Composer app directory:

node_modules/.bin/vite temp/plugins/world-clock

When the chat says the plugin is ready, turn on Dev Server as above.

The Composer Plugin (Sandbox) template, contributed by the Sandbox plugin, runs the same example against any bundled Composer, deployed ones included: the agent builds in an EDGE sandbox with @dxos/* installed from pkg.pr.new at the commit the app was built from, serves dist/ from the container, and offers the manifest URL of the port it exposed.

Both ways need a bundled build of Composer (vite build + vite preview, or a deployed app). A bundled Composer publishes an import map that resolves your plugin’s bare @dxos/*, react and effect imports to the host’s own copies; Composer’s own Vite dev server has no import map, so those imports fail there.

Example: a plugin with its own navtree group

A small plugin in TypeScript that adds a group to every space’s navtree, with one page under it, opened as an article. It builds with the official tooling into a manifest.json and an index.mjs that Composer loads by URL.

Four files:

import { Config2 } from '@dxos/app-framework/config';

export default Config2.make({
  plugin: {
    key: 'org.example.plugin.hello', // must match the key the plugin declares; last segment camelCase
    name: 'Hello',
    icon: { key: 'ph--hand-waving--regular', hue: 'amber' },
    tags: ['labs'], // lists it under Labs in the Plugins registry
  },
});

import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

import { composerPlugin } from '@dxos/app-framework/vite-plugin';

export default defineConfig({
  plugins: [...composerPlugin({ entry: 'src/plugin.tsx' }), react()],
  build: { outDir: 'dist' }, // any directory you serve
});

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "allowImportingTsExtensions": true,
    "types": []
  },
  "include": ["src", "dx.config.ts"]
}

import * as Effect from 'effect/Effect';
import React from 'react';

import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
import * as Capabilities from '@dxos/app-framework/Capabilities';
import * as Capability from '@dxos/app-framework/Capability';
import * as Plugin from '@dxos/app-framework/Plugin';
import * as Surface from '@dxos/app-framework/Surface';
import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
import * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
import * as AppNode from '@dxos/app-toolkit/AppNode';
import * as AppNodeMatcher from '@dxos/app-toolkit/AppNodeMatcher';
import * as AppSurface from '@dxos/app-toolkit/AppSurface';

import config from '../dx.config.ts';

const meta = Plugin.getMetaFromConfig(config);
const GROUP = 'helloGroup';
const GROUP_TYPE = `${meta.profile.key}.group`;
const PAGE = 'helloPage';

const HelloArticle = () => (
  <div style={{ padding: '2rem', fontSize: '2rem' }}>Hello from a plugin!</div>
);

export default Plugin.define(meta).pipe(
  Plugin.addModule({
    id: 'appGraph',
    activatesOn: ActivationEvents.Startup,
    provides: [AppCapabilities.AppGraphBuilder],
    activate: () =>
      Effect.gen(function* () {
        // A group: an uppercase heading in each space's navtree, between CONTENT and SYSTEM.
        const group = yield* AppGraphBuilder.createExtension({
          id: 'helloGroup',
          match: AppNodeMatcher.whenSpace,
          connector: (space) =>
            Effect.succeed([
              AppNode.makeGroup({
                id: GROUP,
                type: GROUP_TYPE,
                label: 'Hello',
                space,
                position: 400,
              }),
            ]),
        });
        // A page in that group. The URL binding is what lets the deck open it.
        const page = yield* AppGraphBuilder.createExtension({
          id: 'helloPage',
          match: AppNodeMatcher.whenNavTreeGroup(GROUP_TYPE),
          url: { key: PAGE, kind: 'singleton', path: [GROUP] },
          connector: (space) =>
            Effect.succeed([
              AppGraphNode.make({
                id: PAGE,
                type: `${meta.profile.key}.page`,
                data: PAGE,
                properties: {
                  label: 'Hello',
                  icon: 'ph--article--regular',
                  selectable: true,
                  draggable: false,
                  droppable: false,
                  space,
                },
              }),
            ]),
        });
        return [
          Capability.contribute(AppCapabilities.AppGraphBuilder, [
            ...group,
            ...page,
          ]),
        ];
      }),
  }),
  Plugin.addModule({
    id: 'surface',
    activatesOn: ActivationEvents.Startup,
    provides: [Capabilities.ReactSurface],
    activate: () =>
      Effect.succeed([
        Capability.contribute(
          Capabilities.ReactSurface,
          // Renders the page's article: the node's `data` is the subject.
          Surface.create({
            id: 'helloArticle',
            filter: AppSurface.literal(AppSurface.Article, PAGE),
            component: HelloArticle,
          }),
        ),
      ]),
  }),
  Plugin.make,
);

A package.json beside them names what the build needs. Pin every @dxos/* package to the build of the Composer you load the plugin into: a release’s npm version, or for a build of an unreleased commit of main, its pkg.pr.new build (https://pkg.pr.new/@dxos/<package>@<commit>). react, react-dom and effect are the host’s own copies at runtime, so match its versions too:

{
  "name": "hello",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@dxos/app-framework": "<version>",
    "@dxos/app-graph": "<version>",
    "@dxos/app-toolkit": "<version>",
    "effect": "<the host's version>",
    "react": "<the host's version>",
    "react-dom": "<the host's version>"
  },
  "devDependencies": {
    "@types/react": "<the host's version>",
    "@vitejs/plugin-react": "^6.0.0",
    "typescript": "^7.0.0",
    "vite": "^8.0.0"
  }
}

Install, typecheck, then build, from the plugin’s directory:

npm install
tsc -p tsconfig.json   # vite does not typecheck
vite build             # writes dist/manifest.json and dist/index.mjs

Bun alone does too, with no node on the machine: bunx @pnpm/exe@10 install (with node-version=24.11.1 in an .npmrc, or pnpm skips the bundler’s native binary), then bun run --bun tsc -p tsconfig.json and bun run --bun vite build. That is how the desktop app’s Composer Plugin project template builds, in a sandbox that holds nothing else.

Serve dist/ (with CORS, if it is on another origin) and load <URL of dist>/manifest.json. After it loads, each space’s navtree shows a HELLO group with a Hello page under it; selecting the page opens it. The version in the manifest comes from a package.json next to dx.config.ts, or 0.0.0 without one.

Things to know:

Import only packages the host shares through its import map — the @dxos/* libraries and react, react-dom and effect; the build leaves those as bare imports. @dxos/plugin-* packages are not shared, so the build bundles whatever you use from them.
Ids are camelCase: the key’s last segment (org.example.plugin.helloWorld, not …hello-world), module ids, graph extension ids, node ids and surface ids. A hyphenated key makes the module throw Invalid DXN when it is imported; a hyphenated extension or surface id is dropped without an error.
AppGraphBuilder.createExtension returns an Effect: yield* it and contribute the extensions it yields.
A group is a heading, not a page: it has no URL binding and shows only once something is under it. Its position orders it among the built-in groups (content 200, system 900).
A singleton page’s node id must equal its URL key, and path names the group it sits under.
Every module lists the capabilities its activate returns in provides.
A plugin that fails to activate is disabled; fix it and re-enable it from the Plugins list (or reload).
The browser caches a module that failed to import, so reload Composer before loading a fixed copy from the same URL.

Example: data, a form and another plugin’s surface

The same plugin grows an ECHO type stored in the space, a form that edits it, and a map drawn by another plugin that follows what the reader selects. The rest of the plugin (navtree group, page, surface) is as above.

Depend on the plugin whose surface you render; enabling yours then enables it too:

export default Config2.make({
  plugin: {
    key: 'org.example.plugin.worldClock',
    name: 'World Clock',
    icon: { key: 'ph--globe-hemisphere-west--regular', hue: 'sky' },
    tags: ['labs'],
    dependsOn: ['org.dxos.plugin.map'],
  },
});

Plugin.addModule(AppCapability.schema([Clock])),

A page that needs the space carries it in the node’s data, and the surface narrows on it:

AppGraphNode.make({ id: PAGE, type: `${meta.profile.key}.page`, data: { type: PAGE, space }, properties: { ... } });

Surface.create({
  id: 'worldClockArticle',
  filter: AppSurface.subject(AppSurface.Article, isPage),
  component: WorldClockArticle,
  props: ({ data: { subject } }) => ({ db: subject.space.db }),
});