Skip to main content

Publish plugins: npm / GitHub / tarball

Pick the right channel between npm / GitHub ref / tarball, the 6-item bundle self-check, and what to verify before publishing — the complete path from your repo to a user's install command.

9 min read

What you'll learn

  • Pick the right distribution channel (npm / GitHub ref / tarball) for your user base
  • Wrap your plugin as a dsh.bundle and self-test via dsh plugin add
  • Know the compatibility / safety checks to run before publishing

Version

Compatible with: dsh 0.1.1-rc.2 (compiled from official apps/cli/README + docs/user/develop/publish/; verify against current docs before publishing)

How to choose between the three channels

DSH plugins aren't tied to a single marketplace — as long as the code is reachable, the CLI can install it. The three mainstream channels have different trade-offs:

ChannelCommand shapeBest forWatch out
npm packagedsh plugin add npm:@scope/name or npx @deepseek-ai/dsh plugin add @scope/nameLong-term maintenance, versioned releases, npm ecosystem (downloads/deps)Need to publish tarball to a registry; prefix with @scope; keep below 10MB (npm default)
GitHub refdsh plugin add github:owner/repo#v1.2.0 or github:owner/repo#mainRapid iteration, no npm overhead; CI auto-tag friendlyRef must be a commit/tag/branch; private repos need a token
tarballdsh plugin add https://example.com/path/to/plugin.tgzInternal enterprise distribution, beta releases, bypass registriesURL must be publicly reachable; you manage version strings; CDN caches may serve stale tarballs

Reference installs:

  • npm style: dsh plugin add npm:@liustack/modlens (details), versions flow through npm registry
  • GitHub ref style: dsh plugin add github:ccch1mneyyy/dsh-TUI#v1.0 (details), tags pin versions
  • The dsh-plugins compatibility-layer org mostly uses GitHub refs to roll back quickly during testing

Six checks before publishing

  1. bundle manifest is complete: root has dsh.bundle (or cordis.patch.yml) with name / version / entry all set
  2. self-test install: run dsh plugin add github:owner/repo on your own repo and confirm it appears in dsh plugin ls without errors
  3. README header three sentences: plugin name + one-line value + install command — the AI wiki on detail pages pulls from here
  4. dshTarget declared: in README or wiki, name the compatible dsh version (Compatible with: dsh 0.1.x gets picked up by machine audit)
  5. License: root has LICENSE with a recognizable SPDX identifier (MIT / Apache-2.0 / BSD-3-Clause etc.)
  6. topic dsh-plugin: GitHub repo carries this topic so awesome-dsh-plugin lists will pick it up

The 5-dimension machine audit badge (N/5 on detail pages) is auto-derived from these six items. Drop one, lose one ✓.

Failure modes

  • "command not found": usually the entry path is wrong, CLI can't locate the apply export
  • "bundle manifest missing": root has no dsh.bundle; CLI falls back to generic npm install but loses Cordis compatibility protection
  • published to npm but no installs: package name lacks dsh- prefix and is hard to discover; awesome-dsh-plugin is the current main discovery channel — submit a PR there

FAQ

Which channel should I ship to first?

Start with GitHub ref while iterating, graduate to npm once the repo stabilizes. Tarball is only for internal distribution.

Can I change the npm version after publishing?

Yes, but follow semver strictly: patch versions can ship silently, minor/major must come with explicit upgrade notes (GitHub Release notes work well).

All tutorials