0
Fork 0
mirror of https://github.com/verdaccio/verdaccio.git synced 2024-12-16 21:56:25 -05:00
verdaccio/website/docs/plugin-middleware.md
Juan Picado 3ad519f0c2 chore: website scaffolding (#1843)
* chore: upload gatsby website

* chore: update header

* chore: add background header

* chore: add ci for website

* Update ci-website.yml

* chore: update patch mach ci

* chore: update ci settings

* chore: update docker version
2021-04-09 17:54:10 +02:00

4.6 KiB
Raw Blame History

id title
plugin-middleware Middleware Plugin

What's an Middleware Plugin?

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

''

API

interface IPluginMiddleware<T> extends IPlugin<T> {
  register_middlewares(app: any, auth: IBasicAuth<T>, storage: IStorageManager<T>): void;
}

register_middlewares

The method provide full access to the authentification and storage via auth and storage. app is the express application that allows you to add new endpoints.

public register_middlewares(
    app: Application,
    auth: IBasicAuth<CustomConfig>,
    storage: IStorageManager<CustomConfig>
  ): void {
    const router = Router();
    router.post(
      '/custom-endpoint',
      (req: Request, res: Response & { report_error?: Function }, next: NextFunction): void => {
        const encryptedString = auth.aesEncrypt(Buffer.from(this.foo, 'utf8'));
        res.setHeader('X-Verdaccio-Token-Plugin', encryptedString.toString());
        next();
      }
    );
    app.use('/-/npm/something-new', router);
  }

The auth and storage are instances and can be extended, but we don't recommend this approach unless is well founded.

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

Generate an middleware plugin

For detailed info check our plugin generator page. Run the yo command in your terminal and follow the steps.

➜ yo verdaccio-plugin

Just found a `.yo-rc.json` in a parent directory.
Setting the project root at: /Users/user/verdaccio_yo_generator

     _-----_     ╭──────────────────────────╮
    |       |    │        Welcome to        │
    |--(o)--|    │ generator-verdaccio-plug │
   `---------´   │   in plugin generator!   │
    ( _´U`_ )    ╰──────────────────────────╯
    /___A___\   /
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

? What is the name of your plugin? custom-endpoint
? Select Language typescript
? What kind of plugin you want to create? middleware
? Please, describe your plugin awesome middleware plugin
? GitHub username or organization myusername
? Author's Name Juan Picado
? Author's Email jotadeveloper@gmail.com
? Key your keywords (comma to split) verdaccio,plugin,middleware,awesome,verdaccio-plugin
   create verdaccio-plugin-custom-endpoint/package.json
   create verdaccio-plugin-custom-endpoint/.gitignore
   create verdaccio-plugin-custom-endpoint/.npmignore
   create verdaccio-plugin-custom-endpoint/jest.config.js
   create verdaccio-plugin-custom-endpoint/.babelrc
   create verdaccio-plugin-custom-endpoint/.travis.yml
   create verdaccio-plugin-custom-endpoint/README.md
   create verdaccio-plugin-custom-endpoint/.eslintrc
   create verdaccio-plugin-custom-endpoint/.eslintignore
   create verdaccio-plugin-custom-endpoint/src/index.ts
   create verdaccio-plugin-custom-endpoint/index.ts
   create verdaccio-plugin-custom-endpoint/tsconfig.json
   create verdaccio-plugin-custom-endpoint/types/index.ts
   create verdaccio-plugin-custom-endpoint/.editorconfig

I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.


⸨ ░░░░░░░░░░░░░░░░░⸩ ⠋ fetchMetadata: sill pacote range manifest for @babel/plugin-syntax-jsx@^7.7.4 fetc

After the install finish, access to your project scalfold.

➜ cd verdaccio-plugin-auth-service-name
➜ cat package.json

  {
  "name": "verdaccio-plugin-custom-endpoint",
  "version": "0.0.1",
  "description": "awesome middleware plugin",
  ...

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