DEV Community: Verdaccio

How to use Verdaccio with GitHub registry

Juan Picado — Sun, 22 Mar 2020 14:50:54 +0000

I've been asked for this couple of times and I want to share how you can achieve a seamless integration GitHub with Verdaccio. Node.js package managers only allow using one registry when you are running an eg: npm install unless you modify the .npmrc and add some specific configuration, but frankly, we can do better using a proxy.

Generating the Token at GitHub

First of all, we need to understand the GitHub registry is not a conventional registry, it does not support all npm commands you are get used to (eg: npm token).

I'd recommend you read first the official documentation at GitHub how to use packages.

Once you have set up and created a personal token in their User Interface (remember you cannot use npm adduser). Copy the token from the website and proceed to log in to your terminal.



$ npm login --registry=https://npm.pkg.github.com
> Username: USERNAME
> Password: TOKEN

The last thing is recovering the token generated by the GitHub registry in the ~/.npmrc file and find the line to verify npm you can use npm commands against GitHub registry.



//npm.pkg.github.com/:_authToken=TOKEN{% raw %}`.
```

One optional step is to publish a package, I have already one published one for my example below.

> This step is required if you have not published packages, otherwise, you don't need to log in, just copy the token.

Great, you have a **token** and that's all you need for *Verdaccio*.

### Installing Verdaccio

Let's imagine you don't know anything about [Verdaccio](https://verdaccio.org/). So here is what it does.

**Verdaccio is a lightweight private proxy registry build in Node.js** 

and with straightforward installation, with no dependencies aside to have installed Node.js.

```
npm install --global verdaccio
```
to run *Verdaccio* just run in your terminal,

```
➜ verdaccio
 warn --- config file  - /Users/user/.config/verdaccio/config.yaml
 warn --- Verdaccio started
 warn --- http address - http://localhost:4873/ - verdaccio/4.5.0
```
for further information I'd recommend read our [documentation](https://verdaccio.org/docs/en/installation).

For this article, we will focus on the **proxy**, which is the most powerful and popular feature by far.

### Hooking the GitHub registry

First of all, you need a published package in the registry, here is mine and as you can see **GitHub only support scoped packages**.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/oydvxn9kuve9ttcsoypq.png)

This example is about how to fetch packages from **npmjs** and **GitHub** registries at the same time without modify the `.npmrc` file.

#### Uplinks

Open the verdaccio configuration file (eg: `/Users/user/.config/verdaccio/config.yaml`) and update the `uplinks` section adding a new registry.

```
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
  github:
    url: https://npm.pkg.github.com
    auth:
      type: bearer
      token: xxxx
```
For demonstration purposes let's copy the token in the example above, populate the config file with `token` is not the best approach, I recommend using *environment variables* with **auth** property, read more about it [here](https://verdaccio.org/docs/en/uplinks#auth-property).

#### Package Access

To install packages, we need the list of dependencies in your `package.json` file. Here is my example:

```
  "dependencies": {
    "@types/babel__parser": "7.1.1",
    "@juanpicado/registry_test": "*",
    "lodash": "*"
  }
```

If you recall, I've published a package in my GitHub profile named `registry_test`, but GitHub requires to access my public package scoped with my user name, that would be `@juanpicado/registry_test`. 


![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/3zdrvka3jh7330q5lm7h.png)

To make it more interesting, I also added a random published public package published by another user named `@types/babel__parser`.

The next step is setting up the **package access** section:

```
packages:
  '@juanpicado/*':
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: github
  '@types/babel__parser':
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: github 
  '@*/*':
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs
```

As we describe in the packages [documentation](https://verdaccio.org/docs/en/packages#usage), the **order is important**. Define the scoped packages you want to match on top of `'@*/*'` and define the `proxy` properties to the name used in the uplink section, for our example would be `proxy: github`.

With such configuration, *Verdaccio* will be able to route the request to the right remote.

```
 http --> 200, req: 'GET https://registry.npmjs.org/lodash' (streaming)
 http --> 200, req: 'GET https://registry.npmjs.org/lodash', bytes: 0/194928
 http <-- 200, user: null(127.0.0.1), req: 'GET /lodash', bytes: 0/17599
 http <-- 200, user: null(127.0.0.1), req: 'GET /lodash', bytes: 0/17599
 http --> 200, req: 'GET https://npm.pkg.github.com/@types%2Fbabel__parser' (streaming)
 http --> 200, req: 'GET https://npm.pkg.github.com/@types%2Fbabel__parser', bytes: 0/1113
 http --> 200, req: 'GET https://npm.pkg.github.com/@juanpicado%2Fregistry_test' (streaming)
 http --> 200, req: 'GET https://npm.pkg.github.com/@juanpicado%2Fregistry_test', bytes: 0/2140
 http <-- 200, user: null(127.0.0.1), req: 'GET /@types%2fbabel__parser', bytes: 0/708
 http <-- 200, user: null(127.0.0.1), req: 'GET /@types%2fbabel__parser', bytes: 0/708
 http <-- 200, user: null(127.0.0.1), req: 'GET /@juanpicado%2fregistry_test', bytes: 0/911
 http <-- 200, user: null(127.0.0.1), req: 'GET /@juanpicado%2fregistry_test', bytes: 0/911
```

As we can observe if we have a close look at the server output.

* `lodash` is routed through -> `https://registry.npmjs.org/` .
* `"@types/babel__parser": "7.1.1"` is routed through -> `https://npm.pkg.github.com/@types%2Fbabel__parser`.
*  `"@juanpicado/registry_test": "*"` is routed through `https://npm.pkg.github.com/@juanpicado%2Fregistry_test'.`.

Verdaccio is able to handle as many remotes you need, furthermore, you can add two *proxy* values as a fallback in case the package is not being found in the first option.

```
packages:
  '@juanpicado/*':
    access: $all
    publish: $authenticated
    unpublish: $authenticated
    proxy: npmjs github
```

Verdaccio will try to fetch from *npmjs* and if the package fails for any reason will retry on *github*. This scenario is useful if you are not 100% sure whether the package is available or not in a specific registry. As a downside, if you add multiple proxies will slow down the installations due to the multiple looks up have to perform. 

```
http --> 404, req: 'GET https://registry.npmjs.org/@juanpicado%2Fregistry_test' (streaming)
 http --> 404, req: 'GET https://registry.npmjs.org/@juanpicado%2Fregistry_test', bytes: 0/21
 http --> 200, req: 'GET https://npm.pkg.github.com/@juanpicado%2Fregistry_test' (streaming)
 http --> 200, req: 'GET https://npm.pkg.github.com/@juanpicado%2Fregistry_test', bytes: 0/2140
 http <-- 200, user: null(127.0.0.1), req: 'GET /@juanpicado%2fregistry_test', bytes: 0/908
 http <-- 200, user: null(127.0.0.1), req: 'GET /@juanpicado%2fregistry_test', bytes: 0/908
```
#### One more thing

During writing this blog post, I've noticed all files retrieved from the GitHub registry are not tarballs like those that come from other registries which always finish with the suffix `*.tgz`.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/auuzx8avfhdtgu65cu5c.png)

## Wrapping up

**Verdaccio** is a powerful lightweight registry that can be used in multiple ways, you can find more about it in our [website](https://verdaccio.org). This project is run by voluntaries and [you can also be part of it](https://github.com/verdaccio/verdaccio/issues/1461).

If you would like to donate, it can be done through [OpenCollective](https://opencollective.com/verdaccio), help us to reach more developers to have a sustainable Node.js registry.

Thanks for using Verdaccio and please, **keep safe, stay at home and wash your hands regularly.**

The crazy story of Verdaccio

Juan Picado — Tue, 25 Dec 2018 11:21:21 +0000

It’s not the first time that I’ve heard the following expression “Thanks for creating Verdaccio”, which actually flatters me, but is really hard to explain in a couple of words that I haven’t created Verdaccio. Perhaps I might be responsible for what is Verdaccio today, but that is a different story. Today I’d like to share the whole story behind this project and how I ended up working on it.

Sinopia “The Origin”

A few years ago in 2013, the main registry (npmjs) was running for a while and at the same time, Alex Kocharin decided to create Sinopia.

The original objective was to create a Private registry and Cache to reduce latency between npmjs and the private registry. By that time npmjs was starting to struggle with their own performance issues and be able to host private packages were not supported yet.

Laurie Voss

@seldo

Nobody needs private @npmjs packages more than npm, Inc.. We need it as much as you do. More.

23:36 PM - 06 Jun 2014

1 8

In fact , Sinopia was created before the big npm fall of November 4th and much after the first registry was running. That incident put on the spotlight that having a packages proxy/cache registry in-house makes total sense, at the same time the project evolved adding interesting features as scopes packages, search on UI, plugins, override public packages etc.

It was clear the project was growing, but something happened in October 2015 where is the date of the latest commit and Alex which is still the current owner decided do not reply to anyone anymore, the reasons are unknown and seem will remain like that forever (he has recent activity in other projects) and since is the unique owner the project remains frozen.

Post-sinopia Era

Early 2016 the Sinopia community started to wonder why so that such good idea with good support just stopped for no reason.

A few months later forks did not take long to appear. The most prominent forks were the following (I’m aware there were much more than these):

Sinopia2: Maybe the most affordable and updated fork which seems to be intended with the idea to merge some PR were in the queue. Still, today seems on having some development but no further new features.
shimmerjs/sinopia: A try from IBM team contributors to provide sinopia with CouchDB support. They did a couple of releases but no much development since the fork (this idea was a PR at Verdaccio for a long time but never was merged).
npm-register: A inspired sinopia fork but created from scratch focused as to be hosted on PaaS services.
verdaccio : And here is where all started, the 0 km started on 5 April 2016 which the “baptism” by cuzzinz suggesting the name that he read on Wikipedia.

Since it will be a fork, follow the subject the original project used but a new “color.” …. verdaccio

Verdaccio as fork

After a couple of months without anyone taking the wheel of the ship John Wilkinson and Trent Earl created the Verdaccio organization on April 2016.

Trend Earl announcing the fork of Sinopia

Originally the project was just another fork but soon started to receive the updates from the PR were in hold in sinopia for a long time and even changes committed on Sinopia2. There was a feeling of lack of commitment and confusion with all the forks, somehow this issue was well addressed by the Verdaccio authors providing a second breath to the project.

And here is where I came in. August 2016 is where I started to contribute as anyone else, my initial role was to fix the unit testing on Node 6 and stabilize the project in a couple of areas helping Trend to answer questions on the forum and work side to side to release the first stable version of Verdaccio v2.0.0 which was the first try to put some order in the project.

If you ask me why I decided to contribute Verdaccio. The reason is I liked the name.

During the fall of 2016 and beginning of 2017, we noticed more adoption and bug reports, but in February 2017 the original authors gave me the ownership of Verdaccio just before v2.1.1 release and they have stepped away of development and currently are just watcher. Nowadays I still feel super happy and grateful for the opportunity to drive this project.

As a side note, in that time, my experience with Node.js was not far away from beginner level even if I had good JS background (I’m a front-end developer until today in my private work experience), I’ve never had the chance to work with Node.js in any workplace, funny huh 😅?. What I learnt about real Node.js development is 100% due Verdaccio and reading open source code.

During early 2017 the project had only ~600 stars and I started to coordinate new contributions and a progressive migration to a modern codebase. I have to highlight the new ideas Meeeeow that brought to the project as semantic commits, the new UI based on React and other interesting things.

When you fork a project GitHub reduces the visibility on Google and Github searches , for that reason I asked Github about it. They kindly removed the fork label that we had for 1 year in our main repository.

The official logo provided by the community

2017 ended with a decent amount of stars (~1,200), thousands of downloads and a new logo, but still, we were not able to do a major release. There were too much to do and lack of knowledge in many areas.

Docker

By that time, Docker was new for me until I saw the first time the Dockerfile and was getting so many tickets related with such topic that forced me to learn really quick to be able to merge contributions which were Chinese for me, what did I do?. Go to Docker meetups and read books. Problem solved. Thankfully the community has a lot of knowledge to share in this area thus I had the opportunity to learn from amazing contributions. Nowadays Docker is the most popular way to use Verdaccio even over the npm installation.

2018 “the year”

Verdaccio overpass sinopia on stars December 2018

I have to admit 2018 was super crazy since the first month the project got really good news and advertised by someone really popular (yeah, that helps a lot) Thanks Dan Abramov. create-react-app started to use as E2E tooling, which was totally new for me that scenario and changed our perspective of this project, later on, followed by another projects as Storybook, pnpm, Eclipse Theia, Hyperledger or Modzilla Neutrino.

At the same time, we released a new website at the beginning of the year which nowadays is insanely popular and has reduced the questions over Github being for users the first line of information, by the way, we were one of the early adopters of Docusaurus. Thanks to Crowdin that have provided a platform for translation and nowadays the community has released 7 full translations of our documentation.

the rate of visits by country on google analytics

By that time a new contributor was getting super active since 2017, Ayush which was using Verdaccio at work. In the beginning, his feedback was useful for real-time usage and nowadays he is also one of the authors for the success of this project in 2018.

After some crazy months working really hard, we manage at May to release Verdaccio 3. That gave us a small pause to rethink what to do as future steps and how to improve our community.

Also, we have boarded Sergio Herrera Guzmán and Priscila Oliveira that have demonstrated a lot of interest about Verdaccio contributing with awesome features as the new release pipeline and the new UI which will be released in 2019. The project currently has ~150 contributors and we are welcoming the new ones with open arms.

I’ve seen written articles about Verdaccio in multiple languages, conference speakers recommending the usage of Verdaccio, generous donations and our chat at Discord more active than ever.

To finish the story and ending 2018 we have created what we defined as the core team, a small group of developers trying to work together in the development of Verdaccio 4.

Current Status

If you wonder how the “governance” works at Verdaccio, we do it in the following way. We have 4 owners (the founders, Juan Picado, Ayush) which we open communication when something important should take place and we ship an internal report every 6 months at GitHub teams threads. We have decided this structure in order to avoid what happened with Sinopia do not happen again. The development decisions are taking at the core team level based on democracy and common sense.

The development communication happens over Discord and we started to encourage code reviews and open discussions about everything. For now, it works, but we are trying to evolve the process and improve it.

Currently, we are working on improving the documentation and create a clean ecosystem of plugins, integrations and new ways to inform, teach new adopters about the usage of the registry and helping to board new contributors that want to be part of the development.

Wrapping Up

As you have read, Verdaccio is not a one author project. It’s a collaboration of many developers that decided don’t let this project die. I always like to think the following if you allow me to quote a simile famous words of Abraham Lincoln

Verdaccio is a project of the community, by the community and for the community.

I’m driving this project today, but does not means I’ll do it forever. I like to share responsibilities with others because nobody is working on Verdaccio full time as it happens with other open source projects.

We want this project alive, updated and as reliable, open source and free option for everybody. Following the principles of sinopia stablished as simplicity, zero configuration and with the possibility to extend it.

Even if some initial developers are not contributing anymore (all we have a life), I’m really grateful for the time they have invested and hoped they back in some point.

Disclaimer

I’m telling this story based on my own research and all the information collected along the latest 2 years, comments, private chats, and social networks.

Setting up Verdaccio on DigitalOcean

Juan Picado — Mon, 19 Nov 2018 05:01:01 +0000

This one of the multiple articles I will write about running Verdaccio on multiple platforms.

This time for simplicity I’ve chosen DigitalOcean that provides affordable base prices and if you want to run your own registry, it’s a good option.

Create a Droplet

Choosing an image before creating a droplet

Create a droplet is fairly easy, it just matters to choose an image and click on create, I personally selected a Node.js 8.10.0 version to simplify the setup.

A view of the droplet panel

While the droplet is created, which takes a matter of seconds the next step is to find a way to log in via SSH, you can find credentials in your email. Keep on mind the droplet provides root access and the next steps I won’t use sudo.

Installing Requirements

As first step we have to install Verdaccio with the following command.

npm install --global verdaccio

We will use npm for simplicity, but I’d recommend using other tools as pnpm or yarn.

We will handle the verdaccio process using the pm2 tool that provides handy tools for restarting and monitoring.

npm install -g pm2

Nginx Configuration

To handle the request we will set up ngnix which is really easy to install. I won’t include in this article all steps to setup the web but you can follow this article.

Once nginx is running in the port 80, we have to modify lightly the configuration file as follow

vi /etc/nginx/sites-available/default

location / {
 proxy\_pass [http://127.0.0.1:4873/](http://127.0.0.1:4873/);
 proxy\_set\_header Host $http\_host;
}

You might pimp this configuration if you wish, but, for simplicity this is good enough for the purpose of this article.

Don’t forget restart nginx in order the changes take affect.

systemctl restart nginx

Since we are using a proxy, we must update the default configuration provided by verdaccio to define our proxy pass domain. Edit the file and add the your domain or IP.

vi /root/verdaccio//config.yaml

http\_proxy: http://xxx.xxx.xxx.xxx/

Running Verdaccio

Previously we installed pm2 and now is the moment to run verdaccio with the following command.

pm2 start `which verdaccio`

Note: notice we are using which due pm2 seems not to be able to run a node global command.

Using Verdaccio

Verdaccio provides a nice UI to browse your packages you can access via URL, in our case get the IP from the DigitalOcean control panel and access verdaccio like http://xxx.xxx.xxx.xxx/ .

Install packages

npm will use the default registry on install, but we are willing to use our own registry, to achieve that use the --registry argument to provide a different location.

npm install --registry http://xxx.xxx.xxx.xxx

Other options I’d suggest if you need to switch between registries is using nrm, to install it just do

npm install --global nrm
nrm add company-registry [http://xxx.xxx.xxx:4873](http://xxx.xxx.xxx:4873/)
nrm use company-registry

With the steps above, you can switch back to other registries in an easy way, for more information just type nrm --help .

Publishing Packages

By default verdaccio requires authentication for publishing, thus we need to log in.

npm adduser --registry http://xxx.xxx.xxx.xxx

Once you are logged, it’s the moment to publish.

npm publish --registry http://xxx.xxx.xxx.xxx

Wrapping Up

As you can see, host a registry is quite cheap and the initial set up might take fairly short time if you have some skills with UNIX.

Verdaccio provides you good performance for a small middle team with the default plugins, you might scale for bigger teams if is need it, but I will write about those topics in future articles.

If you are willing to share your experience in our blog writing about verdaccio being installed on other platforms, just send me a message over our chat at Discord for easy coordination.

Verdaccio 4 alpha release

Juan Picado — Sun, 21 Oct 2018 13:56:55 +0000

Since a couple of months ago, verdaccio@4.0.0 is under development, we want to give you a first update of the current list of features ready to be tested and incoming ones.

Verdaccio 4 UI based on material-ui

What’s new in Verdaccio 4 Alpha? 🐣

Tokens 🛡

Improve security is one of our main goals, we have wanted to improve in one of the most important areas for the users, tokens. Currently the token verification is based on unpack the token for each request and ask the plugin whether the author is authorized. This might be a bit overwhelming if the authentication’s provider is not good handling a big amount of request or is totally unnecessary.

For that reason we are shipping a new way to generate token based on JSON Web Token (JWT) standard. This feature does not replace the current implementation and will remains as optional. To enable JWT on API is quite simple as we show in the following example.

security:
 api:
 jwt:
 sign:
 expiresIn: 60d
 notBefore: 1
 web:
 sign:
 expiresIn: 7d

We will allow to customize JWT by demand, for instance, allowing to expire tokens. We will go deep into the new JWT system in future articles.

Change Password 🔐

Perhaps the most asked question in our forum and a so trivial action that might be no a problem nowadays. We have listen the community and invested time in this important feature.

npm profile set password -ddd --registry http://localhost:4873/

We allow change password via CLI using the npm profile . Currently the support is limited to the htpasswd built-in plugin, but in some point the plugin developers will take advance of this support.

Keep it update 🛰

We want to help you to keep it updated, for that reason we are shipping a CLI notification that display the latest stable version available.

New UI 💅🏻

We are aware that our UI has been simple, but we decided it is the time to scale it up in order to add new features. For that reason we planed a migration to a new UI toolkit that will help ups to achieve that goal, Material-UI.

As a first step we migrated the current UI improving the header. But that’s not all is coming, we have big incoming plans in the next alpha releases, for instance:

Change password from UI
i18n
Improvements in the detail page

We are open to new ideas, feel free to suggest or share your thoughts during this development phase.

Docker 🐳

We have reduced the size of the image and following the best practices adding a namespace VERDACCIO_XXX_XXX for environment variables. Many other new things are planned for our popular image that to this day we have almost 2,5 millions pulls.

Future 🔮

I’d like to share our roadmap wether you are interested to know what is in our TODO list and you invite you to contribute or drop your thoughts in any of our channels, we like to listen feedbacks.

verdaccio/verdaccio

How to install

npm install -g verdaccio@next

or using Docker

docker pull verdaccio/verdaccio:4.x-next

⚠️We highly recommend don’t use alpha versions 🚧in production, but if you are willing to test, always do a backup of your storage and config files. In any case, we are really careful with our deployments and are always highly reliable, but, we are humans after all.

However, if you are using Verdaccio 3, there are some small breaking changes you should keep on mind, specially for those are using environment variables with Docker, all details here.

Contributions and Community 🌍

Verdaccio is an open source project, but also we aims to be a nice community and I’d like to introduce you the team that grain by grain is crafting this amazing project.

Verdaccio · A lightweight private npm proxy registry

We thanks all contributors, either via GitHub or translations, any contribution is gold for us.

Donations 👍🏻

I’d like to reminder our readers that there are other ways to contribute to this project becoming a backer. Furthermore, all contributors are voluntaries and nobody is working full time on this project, but we are aware is getting bigger and deserves some promotion.

verdaccio - Open Collective

For those are already backers and sponsors, thanks so much 👏👏👏.

Juan Picado (胡)

@jotadeveloper

Look what I just got on my mailbox 🔥🔥 ... @verdaccio_npm ..👌🏼 I love them #stickers #nodejs #npm

17:31 PM - 11 Sep 2018

2 6

If you have the chance to meet any of our team members, feel free to ask for stickers (hopefully they will carry some), we use our budget mostly for promotion and you can help us to spread the voice, give your start or just recommend with your colleagues how great is Verdaccio.

Wrapping Up 👋🏼

If you live near Vienna (Austria), we will have a presentation in early next year (January 2019) at ViennaJS meetup, feel free to join us if you want to know more about this project.

ViennaJS January 2019 - Meetups - ViennaJS Monthly Meetups

A future core team meeting will take place between 29th and 30th November at Berlin , we are attending React Day Berlin, feel free to DM if you want to have a chat to any of us.

Verdaccio and deterministic lock files

Juan Picado — Thu, 06 Sep 2018 20:21:42 +0000

Snippet of some random lock file

Lockfiles on node package manager (npm) clients are not a new topic, yarn broke the node package managers world with a term called determinism providing a new file generated after install called yarn.lock to pin and freeze dependencies with the objective to avoid inconstancies across multiple installations.

If you are using a private registry as Verdaccio, it might be a concern committing the lock file in the repo using the private or local domain as registry URL and then someone else due his environment is not able to fetch the tarballs defined in the lock file.

This is merely an issue that all package managers have to resolve, nowadays is not hard to see companies using their own registry to host private packages or using the Verdaccio the power feature uplinks to resolve dependencies from more than one registry using one single endpoint.

How does a lock file look like?

Lock file looks different based on the package manager you are using, in the case of npm as an example looks like this

"[@babel/code-frame](http://twitter.com/babel/code-frame)@7.0.0-beta.44":
 version "7.0.0-beta.44"
 resolved "[http://localhost:4873/@babel%2fcode-frame/-/code-frame-7.0.0-beta.44.tgz#2a02643368de80916162be70865c97774f3adbd9](http://localhost:4873/@babel%2fcode-frame/-/code-frame-7.0.0-beta.44.tgz#2a02643368de80916162be70865c97774f3adbd9)"
 dependencies:
 "[@babel/highlight](http://twitter.com/babel/highlight)" "7.0.0-beta.44"

The snippet above is just a small part of this huge file which nobody dares to deal when conflicts arise. However, I just want you to focus on a field called resolved.

Simple example with Verdaccio as localhost

Let’s imagine you are using Verdaccio and yarn for local purposes and your registry configuration points to.

yarn config set registry http://localhost:4873/

After running an installation, yarn install, a lock file is generated and each dependency will have a field called resolved that points exactly the URI where tarball should be downloaded in a future install. That meaning the package manager will rely on such URI no matter what.

In the case of pnpm the lock file looks a bit different, we will see that in detail later on this article.

// yarn.lock

math-random@^1.0.1:
 version "1.0.1"
 resolved "[http://localhost:4873/math-random/-/math-random-1.0.1.tgz#8b3aac588b8a66e4975e3cdea67f7bb329601fac](http://localhost:4873/math-random/-/math-random-1.0.1.tgz#8b3aac588b8a66e4975e3cdea67f7bb329601fac)"

Let’s imagine you that might want to change your domain where your registry is hosted and the resolved field still points to the previous location and your package manager won’t be able to resolve the project dependencies anymore.

A usual solution is to delete the whole lock file and generate a new one , but, this is not practical for large teams since will drive you to conflicts between branch hard to solve.

So, How can I use a private registry avoiding the resolved field issue?. All clients handle this issue in a different way, let’s see how they do it.

How does the resolved field is being used by …?

npm uses a JSON as a format for the lock file. The good news is since npm@5.0.0 ignores the resolved field on package-lock.json file and basically fallback to the one defined in the .npmrc or via --registry argument using the CLI in case is exist, otherwise, it will use the defined in the resolved field.

// Detect dark theme var iframe = document.getElementById('tweet-862834964932435969-971'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=862834964932435969&theme=dark" }

Nowadays you can use the npm cli with lock file safely with Verdaccio independently the URL where tarball was served. But, I’d recommend to share a local .npmrc file with the registry set by default locally or notify your team about it.

If you are using Yarn the story is a bit different. Until the version 1.9.4, it tries to resolve what lock file defines as a first option.

There are some references on PR, RFCs or tickets opened were they discuss how to address this problem properly and if you are willing to dive into this topic allow me to share the most interesting threads you might follow:

Replace resolved field by hash https://github.com/yarnpkg/rfcs/pull/64#issuecomment-414649518
yarn.lock should not include base domain registry https://github.com/yarnpkg/yarn/issues/3330
Remove hostname from the lock files https://github.com/yarnpkg/yarn/issues/5892

TDLR; Yarn 2.0 has planned to solve this issue in the next major version, to this day sill discussing what approach to take.

https://pnpm.js.org/

pnpm follows the same approach as other package managers generating a lock file but, in this case, the file is being called shrinkwrap.yaml that is based in yaml format.

dependencies:
 jquery: 3.3.1
 parcel: 1.9.7
packages:
 /@mrmlnc/readdir-enhanced/2.2.1:
 dependencies:
 call-me-maybe: 1.0.1
 glob-to-regexp: 0.3.0
 dev: false
 engines:
 node: '\>=4'
 resolution:
 integrity: sha512-bPHp6Ji8b41szTOcaP63VlnbbO5Ny6dwAATtY6JTjh5N2OLrb5Qk/Th5cRkRQhkWCt+EJsYrNB0MiL+Gpn6e3g==
 tarball: /@mrmlnc%2freaddir-enhanced/-/readdir-enhanced-2.2.1.tgz

....

registry: '[http://localhost:4873/'](http://localhost:4873/')
shrinkwrapMinorVersion: 9
shrinkwrapVersion: 3
specifiers:
 jquery: ^3.3.1
 parcel: ^1.9.7

The example above is just a small snippet of how this long file looks like and you might observe that there is a field called registry added at the bottom of the lock file which was introduced to reduce the file size of the lock file, in some scenarios pnpm decides to set the domain is part of the tarball field.

pnpm will try to fetch dependencies using the registry defined within the lockfile as yarn does. However, as a workaround, if the domain changes you must update the registry field manually, it’s not hard to do but, is better than nothing.

pnpm has already opened a ticket to drive this issue, I’ll let below the link to it.

Remove the "registry" field from "shrinkwrap.yaml" · Issue #1353 · pnpm/pnpm

Scoped Registry Workaround

A common way to route private packages is route scoped dependencies through a different registry. This works on npm and pnpm

registry=[https://registry.npmjs.org](https://registry.npmjs.org/)
@mycompany:registry=http://verdaccio-domain:4873/

It does exist any support for at the time of this writing.

In my opinion, this is just a workaround, which depends on the number or scopes you handle to decide whether or not worth it. Furthermore, the package manager will bypass those packages that do not match with the scope and won’t be resolved by your private registry.

Conclusion

package managers are working to solve this issues with backward compatibility and with good performance.

For now, the best solution if you share this concern is using npm until the other clients decide what to do or following the recommendations above for each client.

Five use cases where a npm private proxy fits in your workflow

Juan Picado — Mon, 30 Apr 2018 12:30:02 +0000

This article is about why setting up a npm private proxy is a good idea, going through most common questions that I’ve been asked since contributing to sinopia’s fork verdaccio, and how a developer addresses many use cases that made me appreciate how useful it can be set up a local private proxy