Querying the registry

This is an advanced topic for building your own software against the plugin registry. If you only want to install plugins on an EmDash site, you do not need any of this — enable the registry in your config and use the admin dashboard.

The registry’s discovery side is a public, read-only API. The @emdash-cms/registry-client package wraps it, so you can build a plugin directory, a search page, or a release feed outside of EmDash. The client runs anywhere fetch is available — Node, Workers, the browser, or an Astro site.

Install

The discovery subpath carries no authentication or OAuth dependencies. Install the client and pin it to an exact version:

npm install @emdash-cms/registry-client@0.5.0

List and resolve packages

The following Astro page lists every plugin in a registry:

---
import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

const { packages } = await discovery.searchPackages({ q: "", limit: 50 });
---

<ul>
  {
    packages.map((pkg) => (
      <li>
        <a href={`/plugins/${pkg.did}/${pkg.slug}`}>
          {pkg.profile?.name ?? pkg.slug}
        </a>
        {pkg.latestVersion && <span>v{pkg.latestVersion}</span>}
        <p>{pkg.profile?.description}</p>
      </li>
    ))
  }
</ul>

The link uses pkg.did, which is always present. The publisher handle is best-effort and can be absent, so don’t build URLs from it.

A package detail page fetches a plugin by its DID and slug, then fetches the latest release:

import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

export async function getPlugin(did: string, slug: string) {
  const pkg = await discovery.getPackage({ did, slug });
  const latest = await discovery.getLatestRelease({
    did: pkg.did,
    package: pkg.slug,
  });
  return { pkg, latest };
}

Discovery methods

The client exposes one method per aggregator query:

searchPackages({ q, capability?, limit?, cursor? }) — free-text search, optionally filtered to packages declaring a given access category. Returns { packages, cursor? }.
resolvePackage({ handle, slug }) — resolve a package from a handle and slug.
getPackage({ did, slug }) — fetch a package by its DID and slug.
listReleases({ did, package, limit?, cursor? }) — releases in descending semantic-version order, including yanked releases.
getLatestRelease({ did, package }) — the highest non-yanked release selected by the aggregator.

getPackage() and resolvePackage() can return historicalReleaseCount and releaseHistoryComplete. These fields describe the aggregator’s retained operational history, not publisher-signed metadata. Treat a count of one as a first release only when releaseHistoryComplete is true. Missing or incomplete evidence must not bypass a release-age policy.

getPackageStatus() and resolvePackageStatus() wrap their corresponding package queries and map the safe ListingUnavailable response to { status: "unavailable" }. A successful result has { status: "passed", value }. Use these methods in a user interface that needs to distinguish an indexed but unavailable listing from a missing package without rendering publisher-controlled error content.

Use the withdrawal helper before showing or selecting a release:

import {
  DiscoveryClient,
  type ValidatedReleaseView,
} from "@emdash-cms/registry-client/discovery";
import { evaluateRegistryReleaseWithdrawal } from "@emdash-cms/registry-client/withdrawal";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

export function canShowRelease(release: ValidatedReleaseView) {
  const result = evaluateRegistryReleaseWithdrawal(release, discovery.labelerPolicy);
  return release.release !== null && !result.withdrawn;
}

withdrawn is true when the applicable labels remove the release from use. Invalid label data fails closed: withdrawn and malformed are both true.

Handling untrusted records

The aggregator is an untrusted index that relays records it did not author, so the client validates each one at the boundary. Two rules follow from that:

The profile and release fields can be null. When a relayed record fails validation, the client surfaces it as null rather than failing the whole call, so one malformed record does not blank a search page. Always null-check before reading pkg.profile?.name or latest.release?.artifacts.package.
Validate URL schemes yourself before rendering. Validation checks structure, not URL safety — a uri field can carry a javascript: scheme. Apply your own http/https allow-list before putting any registry-supplied URL into an href or src.

A non-2xx response throws ClientResponseError (re-exported from the package), carrying .error, .description, .status, and .headers. The reference aggregator returns only exact-CID revisions approved by every required positive-label source. An atproto-accept-labelers header declares bare configured DIDs for request and cache identity. The aggregator validates the declaration, but its configured policy remains authoritative.

Filtering by host compatibility

A release can declare environment requirements (an EmDash or Astro version range) in its requires block. The @emdash-cms/registry-client/env subpath evaluates them, so a directory can flag releases that will not run on a given host:

import { checkEnvCompatibility, hostEnvFromVersions } from "@emdash-cms/registry-client/env";
import type { ValidatedReleaseView } from "@emdash-cms/registry-client/discovery";

const host = hostEnvFromVersions("0.37.0", "7.0.0");

// Pass a getLatestRelease() result. The returned array is empty when the
// release runs on this host.
export function envMismatches(latest: ValidatedReleaseView) {
  return checkEnvCompatibility(latest.release?.requires, host);
}

Documentation Index