Plugin dependencies

A plugin can build on other plugins. A team might keep shared hooks and servers in a core plugin, then ship several smaller plugins that all need it. Declaring the dependency means people get core installed and switched on along with whatever needs it, and a plugin never runs half-configured without it.

Declare dependencies

List them in the manifest’s dependencies array:

{
  "name": "deploy-tools",
  "version": "2.1.0",
  "dependencies": ["core", "secrets-helper@acme"]
}

Each entry is a string:

Form	Meaning
`core`	A plugin called `core` in the same marketplace as this plugin.
`secrets-helper@acme`	The plugin `secrets-helper` from the marketplace named `acme`.

A trailing caret constraint such as core@^1.2 is accepted and stripped, so the entry means core. Versions are not compared: the dependency is whatever version its marketplace currently offers.

syntic plugin validate reports a dependencies value that is not an array, and any entry that is not a non-empty string.

What happens at install

When someone installs deploy-tools@acme:

deploy-tools itself is installed first.
Its direct dependencies that are not installed yet are listed in one question: `deploy-tools@acme` needs core@acme, secrets-helper@acme. Install them too? [Y/n]
On yes, each dependency is installed, and then its own dependencies, all the way down. Every dependency is switched on, even one that ships with "defaultEnabled": false.
On no, deploy-tools stays installed but off, with a note saying what it still needs.

Pass -y (or --yes) to skip the question. Without a terminal, such as in CI, the answer is no unless --yes is given. The headless --plugin flag always installs dependencies.

Dependencies on another marketplace

Automatic installs stay within the marketplace of the plugin you asked for. If deploy-tools@acme depends on vault@other, that dependency is refused:

Refused dependency `vault@other`: it is on another marketplace than `deploy-tools@acme`. Install it yourself if you trust it.

This stops a catalog you trust from being used to slip in plugins from one you have never reviewed. Once you install vault@other by hand, the dependency is satisfied.

What happens at load

Every session checks dependencies before loading anything. A plugin whose dependencies are not all installed, enabled and loading is left off, and so is anything that depends on it in turn. Each case is reported:

Plugin deploy-tools@acme is off: it needs core@acme, which is not enabled (or did not load).

These lines appear in syntic doctor under settings problems, and in the stream-json plugin_errors list for scripted runs. The plugin comes back by itself once the dependency is there.

Plugins loaded with --plugin-dir belong to no marketplace, so their bare dependency names match any loaded plugin with that name.

Turning plugins on and off

Enabling a plugin also enables the installed dependencies it needs that are off, and says so: Also enabled `core@acme`, which `deploy-tools@acme` needs. If a dependency is missing or blocked by your organization’s policy, you get a note instead and the plugin stays off.
Disabling or uninstalling a plugin that others rely on prints the plugins that require it. They stay off while it is gone.

Cleaning up

Dependencies installed automatically are remembered in ~/.syntic/plugins/dependency-installs.json. When nothing installed needs one any more, it can go:

Uninstalling a plugin removes the automatic dependencies it leaves unneeded.
syntic plugin prune removes any that are left over.

A plugin you installed yourself is never pruned, even if it is also someone’s dependency. A dependency that a disabled plugin still declares is kept, because you may turn that plugin back on.

Patterns

A team bundle

Make a small plugin whose only job is to pull in a set of others:

{
  "name": "acme-starter",
  "version": "1.0.0",
  "description": "Everything a new engineer at Acme needs",
  "dependencies": ["core", "deploy-tools", "review-helpers"]
}

New starters run one command, syntic plugin install acme-starter@acme --yes, and get the whole set.

Test a plugin with its dependency locally

Load both folders for one run. Bare names resolve between folder plugins:

syntic --plugin-dir ./core --plugin-dir ./deploy-tools

Or keep them side by side and load the parent folder: syntic --plugin-dir ./plugins.

Pin a dependency’s version

Because versions are not compared, pin through the marketplace instead: point the dependency’s catalog entry at a release tag (for example acme/core@core--v1.4.0). See Release a plugin.

Keep dependency chains short. Each plugin in the chain adds its skills to every request, and each one is another thing that can fail to load.

Plugin components Test a plugin