DSH plugin dependencies: peer, dev, or dependencies?
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:
| Field | Answers | Typical content |
|---|---|---|
peerDependencies | Which copy the host should provide | @deepseek-ai/* runtime packages |
devDependencies | What development and tests need | Local copies of those peer packages |
dependencies | Which copy I bring myself | Third-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".
- Plain imports walk Node's ancestor directories, moving upward when the current one lacks the package;
- Each level consults that level's peer declarations, with nearer physical packages winning;
- 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:
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.
{
"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:
pnpm why <package>: exactly one copy; duplicates mean something slipped into dependencies;- Startup log: no
ERR_MODULE_NOT_FOUNDand no peer warnings; - One hot reload: behavior unchanged, so no registration was invalidated by a duplicate;
- Linked install into a clean profile: it loads, so resolution reaches the host.
Three mismatches to compare against:
| Symptom | Cause | Fix |
|---|---|---|
instanceof fails | A shared package exists twice | Move to peer, remove the extra copy |
| Install warns about a peer | dev declared, peer missing | Add both, keep ranges aligned |
| Module missing after linking | Lookup path misses the host | Use 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.
FAQ
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.
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.
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.
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
- DeepSeek Harness docs: packaging and installing plugins· deepseek-harness
- dsh CLI README· deepseek-ai
- deepseek-harness repository· deepseek-ai