DXOS Community Plugins

This repository is the source of truth for the list of community-authored plugins available in DXOS Composer.

The contents of community-plugins.json are fetched at runtime by Composer's plugin registry and rendered in the Community section. Merging a PR here is equivalent to admitting a plugin into the registry.

How it works

1. A plugin author publishes a GitHub Release on their own repository containing a manifest.json and the built ES module(s).
2. The author opens a PR against this repo adding one entry to community-plugins.json:

   { "repo": "owner/repo" }

3. A maintainer reviews the PR (see CONTRIBUTING.md) and merges.
4. Composer's registry picks up the new entry within ~5 minutes (the edge cache refreshes on that interval).

No further PRs are needed for version updates — the registry polls the repo's latest GitHub Release automatically. Composer shows an Update affordance when a newer version is available, and users can roll back via the version picker on the plugin detail page.

Building a community plugin

plugin-excalidraw is the canonical reference implementation — use it as your starting point.

Vite configuration

Use composerPlugin from @dxos/app-framework/vite-plugin in your vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import wasm from 'vite-plugin-wasm';
import { composerPlugin } from '@dxos/app-framework/vite-plugin';
import { meta } from './src/meta';

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

The meta object is your Plugin.Meta — include author and tags for better discoverability in the registry:

// src/meta.ts
import { type Plugin } from '@dxos/app-framework';

export const meta: Plugin.Meta = {
  id: 'com.example.plugin.foo',
  name: 'Foo',
  description: 'A brief description of what the plugin does.',
  author: 'Your Name or Org',
  tags: ['productivity'],
  icon: 'ph--cube--regular',
  iconHue: 'indigo',
};

composerPlugin emits dist/manifest.json alongside the built modules. The manifest lists every asset (entry module, code-split chunks, CSS) so the Composer host can cache them for offline use.

Because @dxos/* dependencies are externalized by the plugin bundle, the version in your package.json controls types and build-time APIs but the host's copy is what runs. In practice this means any version with a compatible API will work — an exact match isn't required. For now, use the latest main dist-tag to stay current with the host:

npm dist-tag ls @dxos/app-framework

This guidance will be updated when 0.9 ships.

Local development

During development you can load your plugin directly from the Vite dev server without a build step. composerPlugin serves a synthetic dev manifest on port 3967 by default — the same port Composer expects — so no URL configuration is needed:

pnpm dev

In Composer, open Settings → Plugins and enable the Dev plugin toggle. It persists across page reloads so HMR-driven refreshes stay connected.

Note: Fast Refresh does not work cross-origin. Edits are picked up on the next manual page reload.

To test the production bundle locally before publishing:

pnpm build && pnpm preview

Enable the same Dev plugin toggle in Settings → Plugins to load the preview build.

Creating a release

This repository ships a reusable GitHub Actions workflow that handles the full release cycle: version bump, build, git tag, and asset upload. Add a single workflow file to your plugin repo:

# .github/workflows/release.yml
name: Release
on:
  workflow_dispatch:
    inputs:
      bump:
        description: 'Version bump'
        required: true
        default: patch
        type: choice
        options: [patch, minor, major]

permissions:
  contents: write

jobs:
  release:
    uses: dxos/community-plugins/.github/workflows/release-plugin.yml@main
    with:
      bump: ${{ inputs.bump }}
    secrets: inherit

Trigger it from the Actions tab in your repo. The workflow will:

1. Bump the version in package.json.
2. Run pnpm build.
3. Commit the bump, tag it (e.g. v0.2.0), and push.
4. Create a GitHub Release with auto-generated notes.
5. Upload all dist/ assets as release artifacts.

Pass node-version or pnpm-version inputs if your project requires specific versions. The workflow source is at .github/workflows/release-plugin.yml.

Register with the community registry

Once you have at least one release published, open a PR adding your entry to community-plugins.json:

{ "repo": "your-github-username/your-plugin-repo" }

Relationship to built-in (Official) plugins

The Official section of Composer's registry lists plugins that ship with Composer itself. The Community section — powered by this repo — lists third-party plugins that users install on demand.

License

The manifest and tooling in this repository are MIT-licensed. Each listed plugin is governed by its own repository's license.