ChatGPTClaudeGrok / X / CursorGemini

DSH plugin dependencies: peer, dev, or dependencies?

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH plugindependenciespeerDependenciespnpmversion compatibility
Two instances of the same library, mismatched types, or a linked install that cannot resolve a module. Usually the dependency sits in the wrong section.

Most dependency bugs in a DSH plugin come from placement, not versions. The plugin installs, the tool runs, and occasionally the log shows a failed instanceof; or the editor is happy while runtime reports a missing method. These are rarely version mistakes. They are usually dependencies in the wrong section.

Three DSH plugin symptoms, one root cause

Two instances. Your plugin imports Service from @deepseek-ai/cordis, and the host has its own copy. The two classes are different functions, instanceof is permanently false, and a service registration appears to succeed while being invisible.

Types disagree. The editor uses the definitions in your node_modules, runtime uses the host's copy, and a small version gap produces "compiles, but the method is missing at runtime".

A linked install cannot resolve a module. A local checkout is installed into a profile, imports a package the host already has, and fails with ERR_MODULE_NOT_FOUND.

The common thread: ownership and resolution are misaligned. Ownership decides whose copy is used; resolution decides whether it can be found.

The three DSH plugin dependency sections

DSH plugin dependency fields are not interchangeable; each answers a different question. The table maps them:

FieldAnswersTypical content
peerDependenciesWhich copy the host should provide@deepseek-ai/* runtime packages
devDependenciesWhat development and tests needLocal copies of those peer packages
dependenciesWhich copy I bring myselfThird-party libs needing their own version, stateless toolkits

One criterion: must this package share the same runtime instance as the host? Yes means peer, no means dependencies, and a copy used only for compilation and tests means dev. Placing it wrong does not fail immediately; it surfaces during hot reload, multi-entry use, or linked installs.

Why dsh packages appear twice

The most counterintuitive DSH plugin rule: the same package appears in both peerDependencies and devDependencies.

  • Runtime: Harness's runtime resolution already includes the host copy, so no duplicate is loaded;
  • Development: the dev copy gives you types, unit tests, and standalone examples.

Peer only? The editor cannot find types locally, tests break, and pnpm warns about a missing peer after someone installs your package. Dependencies only? Runtime may install a second copy, and the first symptom appears.

Write a reasonably wide peer range. A narrow range blocks your plugin at the engines.dsh check when the host takes a minor upgrade, which looks like installation or startup being refused.

DSH plugin resolution during linked installs

In a DSH plugin linked install, the checkout keeps its own node_modules. That explains "works in the example directory, cannot find it inside the profile".

  1. Plain imports walk Node's ancestor directories, moving upward when the current one lacks the package;
  2. Each level consults that level's peer declarations, with nearer physical packages winning;
  3. The link target may have no package.json, and an ancestor peer still applies.

The question is not whether node_modules exists but how far the lookup path reaches. The host lives in the profile's dependency tree; your checkout is elsewhere, so they share no ancestor chain.

To see where runtime actually resolves, ask Node directly:

bash
node -e "console.log(require.resolve('@deepseek-ai/cordis', { paths: ['./'] }))"

If the output lands in your own node_modules instead of the profile tree, a second copy exists — exactly the precondition for a failed instanceof. When you need an explicit path, require.resolve(name, { paths }) is the native query; plain imports will not cross directories on their own.

npm, desktop, and source launches share these rules. Working locally does not imply working inside a profile, and vice versa; verify both.

A DSH plugin package.json to copy from

This DSH plugin package.json shows all three sections in place, ready to compare against.

json
{
  "name": "dsh-my-plugin",
  "type": "module",
  "main": "index.js",
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
  "engines": { "dsh": ">=0.2.0 <0.3.0" },
  "peerDependencies": {
    "@deepseek-ai/cordis": ">=0.2.0 <0.3.0",
    "@deepseek-ai/dsh-tools": ">=0.2.0 <0.3.0"
  },
  "devDependencies": {
    "@deepseek-ai/cordis": "^0.2.0",
    "@deepseek-ai/dsh-tools": "^0.2.0"
  },
  "dependencies": { "undici": "^6.0.0" }
}

Three observations: undici sits in dependencies because it is an ordinary third-party library needing its own version; the two dsh packages sit in peer and dev with matching ranges; engines.dsh is declared separately and checked at install and startup.

Do not put typescript in dependencies. It ships to users unless your plugin genuinely compiles code at runtime.

DSH plugin dependency self-checks and mismatches

After changing DSH plugin dependencies, verify in four steps:

  1. pnpm why <package>: exactly one copy; duplicates mean something slipped into dependencies;
  2. Startup log: no ERR_MODULE_NOT_FOUND and no peer warnings;
  3. One hot reload: behavior unchanged, so no registration was invalidated by a duplicate;
  4. Linked install into a clean profile: it loads, so resolution reaches the host.

Three mismatches to compare against:

SymptomCauseFix
instanceof failsA shared package exists twiceMove to peer, remove the extra copy
Install warns about a peerdev declared, peer missingAdd both, keep ranges aligned
Module missing after linkingLookup path misses the hostUse require.resolve paths or change the install method

One last rule: do not fix dependency problems by installing again. A second install only makes the duplicate harder to see; correct the ownership first, then talk about versions.

With dependencies placed correctly, plugin behavior becomes predictable. For the bundle manifest, read packaging a bundle; for build permissions on git installs, read publishing to npm; for version ranges, read plugin version compatibility.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Should @deepseek-ai packages used by a plugin go in peerDependencies or dependencies?

dsh packages that must share the host instance go in both peerDependencies and devDependencies. Runtime uses the host copy; the dev copy is for type checking and standalone tests, so a second instance never appears.

Why do two copies of the same DSH plugin library appear and make instanceof checks fail?

Either a DSH plugin lists the package in dependencies, or an unmet peer range made pnpm install another copy. Shared-instance packages must use peer so runtime resolves to the host copy; two copies break class identity and singleton state.

After a linked install, why can the plugin not find a dependency the host already has?

With a DSH plugin linked install, the checkout keeps its own node_modules, and plain imports follow Node's ancestor lookup for peer declarations. When the path does not reach the host tree, resolution fails; use require.resolve with a paths option when you need an explicit location.

Does a stateless DSH plugin utility package with no host coupling also need peerDependencies?

No, a stateless DSH plugin utility does not need peerDependencies. Stateless dsh toolkits are ordinary dependencies and belong in dependencies. Peer is required only when a package must share the same runtime instance as the host.

Related Terms

peerDependencies
peerDependencies is a field that declares dependencies a plugin expects the host to provide, so runtime resolves to the host instance and avoids duplicate state.— DeepSeek Harness docs
devDependencies
devDependencies is a section that installs only for development and testing, used for type checking and standalone test runs and excluded from runtime resolution.— DeepSeek Harness docs
linked install
A linked install is an install that mounts a local checkout into a profile; the target keeps its own node_modules and module resolution still follows ancestor lookup.— DeepSeek Harness docs
runtime resolution
Runtime resolution is how Harness decides which copy a dependency points to when starting a profile, shared by npm, desktop, and source launches.— DeepSeek Harness docs

Sources