Middleware Plugin

What's a Middleware Plugin?

Middleware plugins have the capability to modify the API (web and cli) layer, either adding new endpoints or intercepting requests.

API

The interface lives in @verdaccio/core, under the pluginUtils namespace:

import { pluginUtils } from '@verdaccio/core';

interface ExpressMiddleware<PluginConfig, Storage, Auth> extends Plugin<PluginConfig> {
  register_middlewares(app: Express, auth: Auth, storage: Storage): void;
}

note

The type parameters are declared in the order <PluginConfig, Storage, Auth>, but register_middlewares receives auth before storage. The compiler will not catch the two being swapped when both are any.

Storage and Auth are the types of the instances Verdaccio injects. A plugin that only needs auth can declare {} for Storage, as the generator template does.

register_middlewares

app is the Express application, so the method can mount any router or middleware on it. auth and storage are the live instances and can be extended, though we don't recommend it unless well founded.

import express, { type Express } from 'express';
import type { Auth } from '@verdaccio/auth';
import { pluginUtils } from '@verdaccio/core';
import type { Logger } from '@verdaccio/types';

export default class CustomEndpoint
  extends pluginUtils.Plugin<CustomConfig>
  implements pluginUtils.ExpressMiddleware<CustomConfig, {}, Auth>
{
  readonly logger: Logger;

  public constructor(config: CustomConfig, options: pluginUtils.PluginOptions) {
    super(config, options);
    this.logger = options.logger;
  }

  public register_middlewares(app: Express, _auth: Auth): void {
    const router = express.Router();

    router.post('/custom-endpoint', express.json({ limit: '10mb' }), (req, res, next) => {
      this.logger.info({ url: req.url }, 'custom-endpoint: incoming request');
      res.setHeader('x-verdaccio-middleware', 'demo');
      next();
    });

    app.use('/-/npm/v2/my-endpoint', router);
  }
}

This is the same shape the plugin generator scaffolds, so running it is the quickest way to get a compiling starting point.

A good example of a middleware plugin is the verdaccio-audit.

Overwriting HTTP Security Headers {#overwrite-http-security-headers]

By default, Verdaccio sets the following HTTP headers. If you have other security requirements, you can overwrite these settings using a middleware plugin (Verdaccio 6.2.5 or higher).

Header	Verdaccio Setting
Content-Security-Policy	connect-src 'self'
X-Content-Type-Options	nosniff
X-Frame-Options	deny
X-XSS-Protection	1; mode=block

Generate a middleware plugin

Run yo verdaccio-plugin and pick middleware when asked for the plugin type; the plugin generator page covers installation and the full prompt list. The scaffold it produces is the example shown above, already compiling against the current @verdaccio/core.

The middleware are registrered after built-in endpoints, thus, it is not possible to override the implemented ones.

List Community Middleware Plugins

• verdaccio-audit: verdaccio plugin for npm audit cli support (built-in) (compatible since 3.x)

• verdaccio-profile-api: verdaccio plugin for npm profile cli support and npm profile set password for verdaccio-htpasswd based authentificaton

• verdaccio-https Verdaccio middleware plugin to redirect to https if x-forwarded-proto header is set

• verdaccio-badges A verdaccio plugin to provide a version badge generator endpoint

• verdaccio-openmetrics Verdaccio plugin exposing an OpenMetrics/Prometheus endpoint with health and traffic metrics

• verdaccio-sentry sentry loggin errors

• verdaccio-pacman Verdaccio Middleware Plugin to manage tags and versions of packages