verdaccio/website/blog/2021-04-14-verdaccio-5-migration-guide.md

author	authorURL	authorFBID	title
Juan Picado	https://twitter.com/jotadeveloper	1122901551	Verdaccio 5 migration guidelines

Verdaccio 5 will introduce a few breaking changes, either way the migration should be light for the most of the users, here the big details.

Node.js requirements

The latest Node.js v12 is required to run verdaccio. The upgrade only affects those are not using the Docker.

Verdaccio goes hand to hand with the official Node.js releases roadmap.

We recommend, always try to use the latest LTS version to avoid next major forces you to upgrade Node.js again.

Pino.js is the new logger

Verdaccio replaces Bunyan by Pino.js as logger, with the objective to improve the performance and delegate some features to the external tools. The new logger configuration does not support multiple streams, thus the configuration must contain one single object.

Pretty logging

Verdaccio logging pretty print is a distinguished feature the very first time verdaccio commands runs.

 http <-- 200, user: test(127.0.0.1), req: 'GET /is-accessor-descriptor/-/is-accessor-descriptor-1.0.0.tgz', bytes: 0/3250
 http <-- 200, user: test(127.0.0.1), req: 'GET /extend-shallow/-/extend-shallow-3.0.2.tgz', bytes: 0/3210
 http <-- 200, user: test(127.0.0.1), req: 'GET /define-property/-/define-property-2.0.2.tgz', bytes: 0/4047
 http <-- 200, user: test(127.0.0.1), req: 'GET /mute-stream/-/mute-stream-0.0.8.tgz', bytes: 0/2663
 http <-- 200, user: test(127.0.0.1), req: 'GET /ms/-/ms-2.1.2.tgz', bytes: 0/3017
 http <-- 200, user: test(127.0.0.1), req: 'GET /mkdirp/-/mkdirp-0.5.1.tgz', bytes: 0/4991

But is expensive in and not recommended to using in production environment, thus, if the environment variable NODE_ENV=production is detected, it will fall back automatically to json format.

One tecnical reasons is that pino.final does not work with prettier option.

To improve the performance of your registry, always use format: json in production.

Multiple streams

Even if is supported by Pino.js is not recommended for performance reasons. The log property only recognize one single option. If you were using this feature and want it back, feel free to open a discussion or contribute as opt-in feature.

logs: { type: stdout, format: pretty, level: http }

FYI: pino v7 might bring back a good performant multi-streams support, this feature might be restored in the future.

Rotating file is not longer supported

Pino.js does not support log rotation, thus if you were using this feature is recommended use an external tool.

 // this is not longer valid
 {type: rotating-file, format: json, path: /path/to/log.jsonl, level: http, options: {period: 1d}}

Deprecation

Old configuration won't crash the application, rather will display a deprecation warning and will use the very first option in your configuration as fallback. Consider update your configuration due in the next major will throw an error.

➜  verdaccio
 warn --- config file  - /home/xxxx/.config/verdaccio/config.yaml
(node:22047) Warning: deprecate: multiple logger configuration is deprecated, please check the migration guide.
(Use `node --trace-warnings ...` to show where the warning was created)
 warn --- Plugin successfully loaded: verdaccio-htpasswd
 warn --- Plugin successfully loaded: verdaccio-audit
 warn --- http address - http://localhost:4873/ - verdaccio/5.0.0-alpha.0

npm token

The command npm token has been an experiment in Verdaccio 4 and on this major release is enabled by default, but was based on LevelDB which requires a C and Python compiler on install to make it work. By request has been removed and replaced by a pure JS solution.

The default token database now is plain json file .token-db.json and is located in the same directory as .verdaccio-db.json, with this format:

{
  "jpicado": [
    {
      "user": "jpicado",
      "token": "MWFlM...yZDBl",
      "key": "4201e4bc47c31b3434034e40b5c35175",
      "cidr": [],
      "readonly": false,
      "created": 1609512433710
    },
    {
      "user": "jpicado",
      "token": "ZjQwZ...wYTE1",
      "key": "cc249bc2f4d248308733d70291acdc2a",
      "cidr": [],
      "readonly": false,
      "created": 1609512441024
    }
  ],
  "test": [
    {
      "user": "test",
      "token": "M2RiM...0Mzhj",
      "key": "2ae85deba977e00fb099d323173c925a",
      "cidr": [],
      "readonly": false,
      "created": 1609533131779
    }
  ]
}

Tokens are not being storage, just small part of it, the key is just a random uuid.

Breaking Changes

If you were using npm token in verdaccio 4, most likely the database would need to be removed and created from scratch. Remove the old database and on restart Verdaccio will generate a new one.

url_prefix improved behavior

The new internal logic builds correctly the public url, validates the host header and and bad shaped url_prefix.

eg: url_prefix: /verdaccio, url_prefix: verdaccio/, url_prefix: verdaccio would be /verdaccio/

A new public url environment variable

The new VERDACCIO_PUBLIC_URL is intended to be used behind proxies, this variable will be used for:

• Used as base path to serve UI resources as (js, favicon, etc)
• Used on return metadata dist base path
• Ignores host and X-Forwarded-Proto headers
• If url_prefix is defined would be appened to the env variable.

VERDACCIO_PUBLIC_URL='https://somedomain.org';
url_prefix: '/my_prefix'

// url -> https://somedomain.org/my_prefix/

VERDACCIO_PUBLIC_URL='https://somedomain.org';
url_prefix: '/'

// url -> https://somedomain.org/

VERDACCIO_PUBLIC_URL='https://somedomain.org/first_prefix';
url_prefix: '/second_prefix'

// url -> https://somedomain.org/second_prefix/'

Custom favicon, the new web.favicon property

The favicon can be set either as url or absolute path in your system.

Local absolute path

web:
  title: Verdaccio
  favicon: /home/user/favicon.ico

Ensure the same user that runs the server also has permissions to access the resource you define here.

By URL

web:
  title: Verdaccio
  favicon: https://somedomain.org/favicon.ico

If the logo is not defined, will fetch (and bundled in) the custom verdaccio favicon

UI changes to consider

The new UI may looks the same, but under the hood has consideriable changes:

• Does not contain any CSS, SVG or Fonts anymore: The UI is JS 100% based.
• It uses emotion and <styles> are generated on runtime by JS.
• Fonts now depends of your system, by default define a set of the most common ones.

Web new properties for dynamic template

The new set of properties are made in order allow inject html and JavaScript scripts within the template. This might be useful for scenarios like Google Analytics scripts or custom html in any part of the body.

• metaScripts: html injected before close the head element.
• scriptsbodyBefore: html injected before close the body element.
• scriptsBodyAfter: html injected after verdaccio JS scripts.

web:
  scriptsBodyAfter:
    - '<script type="text/javascript" src="https://my.company.com/customJS.min.js"></script>'
  metaScripts:
    - '<script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.slim.min.js"></script>'
    - '<script type="text/javascript" src="https://browser.sentry-cdn.com/5.15.5/bundle.min.js"></script>'
    - '<meta name="robots" content="noindex" />'
  scriptsbodyBefore:
    - '<div id="myId">html before webpack scripts</div>'

UI custom plugins themes

If you have a custom UI plugin for the them you will need to adapt your build to the new requirements.

The previous version you only need to return a function with a string and the path of the directory.

const path = require('path');

module.exports = () => {
  return path.join(__dirname, 'static');
};

Since Verdaccio 5 the module must return an object and the index.html is ignored since support dynamic rendering, eg:

  staticPath: '/somePath/node_modules/verdaccio-theme-custom/static',
  manifest: {
    'main.js': '-/static/main.c21a97b1dbe8456a9c76.js',
    'runtime.js': '-/static/runtime.c21a97b1dbe8456a9c76.js',
    'NotFound.js': '-/static/NotFound.c21a97b1dbe8456a9c76.js',
    'Provider.js': '-/static/Provider.c21a97b1dbe8456a9c76.js',
    'Version.js': '-/static/Version.c21a97b1dbe8456a9c76.js',
    'Home.js': '-/static/Home.c21a97b1dbe8456a9c76.js',
    'Versions.js': '-/static/Versions.c21a97b1dbe8456a9c76.js',
    'UpLinks.js': '-/static/UpLinks.c21a97b1dbe8456a9c76.js',
    'Dependencies.js': '-/static/Dependencies.c21a97b1dbe8456a9c76.js',
    'Engines.js': '-/static/Engines.c21a97b1dbe8456a9c76.js',
    'Dist.js': '-/static/Dist.c21a97b1dbe8456a9c76.js',
    'Install.js': '-/static/Install.c21a97b1dbe8456a9c76.js',
    'Repository.js': '-/static/Repository.c21a97b1dbe8456a9c76.js',
    'vendors.js': '-/static/vendors.c21a97b1dbe8456a9c76.js',
    '718.c21a97b1dbe8456a9c76.js': '-/static/718.c21a97b1dbe8456a9c76.js',
    '238.c21a97b1dbe8456a9c76.js': '-/static/238.c21a97b1dbe8456a9c76.js',
    '73.c21a97b1dbe8456a9c76.js': '-/static/73.c21a97b1dbe8456a9c76.js'
  },
  manifestFiles: { js: [ 'runtime.js', 'vendors.js', 'main.js' ] }

• staticPath: is the same data returned in Verdaccio 4.
• manifest: A webpack manifest object.
• manifestFiles: A object with one property js and the array (order matters) of the manifest id to be loaded in the template dynamically.

Manifest and Webpack

Verdaccio uses the webpack manifest object to render the html dynamically, in combination with the manifestFiles the application understand what to render.

Currently only support js but if you also need css, we are open to discuss it and further improvements.

const { WebpackManifestPlugin } = require('webpack-manifest-plugin');

  plugins: [
    ...
    new WebpackManifestPlugin({
      removeKeyHash: true,
    }),
    ...
  ],

Troubleshooting

After upgrade I don't see packages on the UI

This migth be the storage is not being located, if you are using this format in your config.yaml

storage: ./storage

Use an absolute path instead, more info here.