Verdaccio Plugin Maintenance

Plugins

This repository ships a small set of bundled plugins and owns the contracts every third-party plugin implements. The work here is maintenance: fixing the bundled plugins, keeping the contracts stable, and making sure plugins load. Writing a new plugin is not repository work.

New plugins are not accepted without a discussion first

A PR that adds a new bundled plugin under packages/plugins is not accepted unless an accepted discussion thread exists for it in the repository's GitHub Discussions (https://github.com/verdaccio/verdaccio/discussions, category Ideas). The discussion settles whether the capability belongs in core, in a bundled plugin, or in an external package, and who maintains it. When asked to add a bundled plugin:

• Look for the discussion and read the maintainers' conclusion. Without one, do not start the PR; report that the change needs a discussion thread first and what it should argue (the problem, why configuration and existing plugins do not cover it, the maintenance cost).
• With an accepted discussion, link it from the PR body and follow "Adding a bundled plugin" below.

New third-party plugins live in their own repositories, outside this one. Point people to the website docs (https://verdaccio.org/docs/plugins and the plugin-auth, plugin-storage, plugin-middleware, plugin-filter, plugin-theme pages); the contracts below are the same, and @verdaccio/plugin-verifier checks the result. The scaffolding tools for external plugins are not used in this repository.

The bundled plugins

packages/tools/verdaccio-*-fake-plugin are test fixtures for the loader, not plugins to maintain.

The contracts

The interfaces live in packages/core/core/src/plugin-utils.ts (pluginUtils), the shared types in @verdaccio/types. Every plugin extends pluginUtils.Plugin<Config> and is constructed as (pluginConfig, { config, logger }).

Changing a contract is a breaking change for every third-party plugin. Adding an optional method (as allow_stage was added) is backwards compatible; renaming, removing, changing a signature, or turning a callback into a promise is major: it needs a major changeset, an entry in docs/migrations-guide.md, the bundled plugins updated in the same PR, and a look at the external plugins the organisation maintains (verdaccio-aws-s3-storage, verdaccio-google-cloud, verdaccio-azure, verdaccio-auth-ldap, ...) so they can be ported. The loader's sanity checks in plugin-utils.ts are part of the contract too.

Semantics the bundled plugins rely on and that a fix must preserve:

• Auth chain. Plugins run in config order; authenticate answers cb(null, groups) on success, cb(null, false) to let the next plugin try, and a VerdaccioError (errorUtils.getUnauthorized(API_ERROR.BAD_USERNAME_PASSWORD)) to stop. The allow_* methods honour $all, $anonymous, $authenticated, and the user's groups exactly as auth-memory does; a change there alters package-access rules for every deployment.
• Storage. StorageHandler is promise-based; readTarball/writeTarball return Node streams and receive an AbortSignal; writes are atomic and fail-safe; updatePackage(name, async manifest => manifest) serialises concurrent updates to the same manifest; a failed writeTarball leaves nothing behind. Only one storage plugin is used (the first loaded, with a warning).
• Middleware. register_middlewares(app, auth, storage) mounts routes on the Express app; protect them with auth.apiJWTmiddleware() rather than parsing tokens. audit is the default when middlewares: is empty.
• Filter. filter_metadata(manifest) returns a new manifest and runs on every packument read; package-filter shows the versions/time/dist-tags/_distfiles cleanup that must stay consistent.
• Theme. A factory returning { staticPath, manifest, manifestFiles: { js, css } }; only the first theme is used.

How plugins load

asyncLoadPlugin in packages/loaders/src/plugin-async-loader.ts is the only loader, used by auth, store (storage and filters), server/express (middleware) and web (theme), and by @verdaccio/plugin-verifier:

• Key foo resolves to package verdaccio-foo (verdaccio-theme-foo for themes); server.pluginPrefix replaces the prefix. A scoped key is used verbatim.
• With plugins: ./plugins in the config, <plugins dir>/<package name> is tried first (relative to the config file, so configPath must be set), then Node resolution from node_modules.
• The export is a default class (new plugin.default(config, options)) or a CJS factory function. require() is tried first, import() second; the entry point for a folder is read from exports['.'], then module, then main.
• A plugin that fails the category's sanity check is logged and skipped; the registry keeps starting. A throwing constructor is only guaranteed to be caught this way when loaded from a configured plugins: folder (that path wraps executePlugin in a try/catch); the npm-resolved (node_modules) path calls executePlugin unguarded, so a throwing constructor there currently propagates out of asyncLoadPlugin instead of being skipped — a known loader gap, not a guarantee.

Loader changes are tested in packages/loaders/test and through every bundled plugin's plugin-load.spec.ts; run both.