Installing DSH Plugins

Where plugins come from

DSH plugins are distributed as npm packages, with source hosted on GitHub. Three places to look:

  • The dsh-plugin topic on GitHub: the official recommendation is that plugin authors tag their repos with it so they are easy to find;
  • The npm registry: published as @scope/xxx packages;
  • The dsh.plus plugin library: every listed plugin comes with a copy-ready install command.

How it works: profiles

Each runnable composition in DSH is a profile, stored under $DSH_HOME/profiles/<name>. The web profile, started by dsh web, is the usual target. The dsh plugin command manages a profile’s plugins: it forwards its arguments to pnpm inside the profile directory, then appends any installed package that declares dsh.bundle to the profile’s dsh.profile.bundles list, making it a config layer. So have pnpm installed before using dsh plugin.

Install into the web profile

dsh plugin --profile web add <package>

For example, a package published to npm:

dsh plugin --profile web add dsh-hello-plugin

You can also install straight from GitHub (github:owner/repo, or any pnpm-supported git spec):

dsh plugin --profile web add github:you/hello-plugin

Git installs pull source, not build output: the author must provide a prepare script that builds at install time. pnpm 10+ refuses to run prepare scripts of git dependencies until explicitly allowed, so the first add fails and prints a hint — put the exact package key from the error into that profile’s pnpm-workspace.yaml under allowBuilds and run add again:

allowBuilds:
  dsh-hello-plugin: true

Treat this grant seriously: it lets that package’s code execute on your machine during install. Only allowlist source you trust, and prefer pinning a commit (github:you/hello-plugin#<sha>).

To avoid the git build dance entirely, ask the author to ship a tarball and install it locally:

dsh plugin --profile web add ./hello-plugin-0.1.0.tgz

Verify the install

Before launching, dump the composed config to confirm the layer is active:

dsh --profile web --dump-config

The output shows a bundle layer marked # == <package>. You can also ask where a package came from:

dsh plugin --profile web why dsh-hello-plugin

Finally start dsh web and exercise the plugin’s features in the Web UI; working behavior plus logs confirm it.

Remove

dsh plugin --profile web remove dsh-hello-plugin

This removes both the dependency and its config layer. To temporarily disable a plugin instead of uninstalling, edit the profile’s cordis.patch.yml and disable or remove the corresponding row.

Local development: patch overlays

A plugin under development doesn’t need installing — load it with a --patch overlay:

pnpm dsh web --patch ./scratch-plugin/cordis.yml

See Your First Cordis Plugin and Cordis, Level Up for details.