Registry

Extensions are resolved from a registry at runtime over HTTP — the same model as shadcn/ui. The default registry is the @getdashfy namespace, served from https://registry.dashfy.dev/r. A Dashfy registry item describes an npm package plus setup metadata, so "applying" an extension installs the package and runs codemods, rather than copying source files.

Registry items

Each extension publishes a <name>.json registry item that validates against registry-item.json. It describes the npm package, its dependencies, required environment variables, the widgets it provides, and a starter dashboard block. Items can declare registryDependencies, which are resolved and applied first when the item is added.

The item's docs field (surfaced by dashfy docs and the MCP get_docs_for_items tool) is authored in each extension's package.json under dashfy.docs and copied into the registry item by dashfy registry build.

Custom & third-party registries

Anyone can publish a registry: serve <name>.json files plus an index.json catalog at a public URL, declare the namespace in your dashfy.json, and install with dashfy add @yourscope/widget. Items can also live in a GitHub repo (under r/<name>.json) and be installed with dashfy add owner/repo/widget.

{
  "registries": {
    "@acme": "https://acme.com/r/{name}.json"
  }
}

For private/authenticated registries, use the object form with ${ENV_VAR} placeholders that resolve from your .env:

{
  "registries": {
    "@acme": {
      "url": "https://acme.com/r/{name}.json",
      "headers": { "Authorization": "Bearer ${ACME_TOKEN}" }
    }
  }
}

dashfy registry add [registries...]

Adds custom registries to your dashfy.json (merged over the built-in @getdashfy). Accepts a bare namespace resolved from the discovery index, or an explicit namespace=url pair.

Resolve @acme from the hosted discovery index:

pnpm dlx dashfy@latest registry add @acme

Declare a namespace with an explicit URL template (must contain {name}):

pnpm dlx dashfy@latest registry add @acme=https://acme.com/r/{name}.json

dashfy registry remove [registries...]

Removes custom registries from your dashfy.json — the inverse of registry add. Removing a namespace that is not configured is a safe no-op, and the built-in @getdashfy namespace can never be removed.

pnpm dlx dashfy@latest registry remove @acme

Discovery index (registries.json)

The CLI resolves bare namespaces from a hosted discovery index at https://registry.dashfy.dev/registries.json, which maps each public @namespace to its URL template plus optional name, description, and homepage. Override its location with DASHFY_REGISTRIES_URL for offline work or testing.

dashfy registry build [packages]

Builds the hosted registry artifacts (<name>.json per extension + index.json) from the dashfy metadata field of each extension.

With --from-npm it reads the latest manifest each listed package has published. This is how the files served at registry.dashfy.dev are produced: extensions live in their own repositories, so npm — not any single checkout — is the source of truth for what the catalog serves.

pnpm dlx dashfy@latest registry build --from-npm apps/registry/extensions.json

The list file is { "packages": ["@scope/ext-name", ...] }. A package that cannot be fetched or has no dashfy field fails the build instead of being skipped, so a transient error cannot publish a catalog that is missing extensions. Override the npm origin with DASHFY_NPM_REGISTRY_URL to build against a mirror or a local directory of manifests.

Without --from-npm, the command reads local ext-* package directories instead. Use this to preview an extension's registry item before publishing it:

pnpm dlx dashfy@latest registry build ./packages

dashfy registry validate [dir]

Validates a built registry directory before publishing: it checks that index.json and every <name>.json match the schemas, that filenames match item names, that there are no duplicates, that the index is in sync, and that local registryDependencies resolve within the same registry. Exits non-zero on failure.

pnpm dlx dashfy@latest registry build && npx dashfy@latest registry validate