How to use a private npm registry like FontAwesome Pro

How to use a private npm registry like FontAwesome Pro

Many organizations do not exclusively rely on public npm packages. In most cases when you want to reuse internal libraries or packages like FontAwesome Pro, you'll need to provide npm with your custom npm registry and auth token.

In this guide we explain how you can use private npm registries in WunderPreview on the example of FontAwesome Pro and how to keep your auth tokens safe.

Status quo

If your private npm registry isn't set up right, your builds will fail when running npm install or yarn install and you'll receive the following error.

$ npm i @fortawesome/fontawesome-pro
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@fortawesome%2ffontawesome-pro - Not found
npm ERR! 404 
npm ERR! 404  '@fortawesome/fontawesome-pro@latest' is not in the npm registry.
npm ERR! 404 You should bug the author to publish it (or use the name yourself!)
npm ERR! 404 
npm ERR! 404 Note that you can also install from a
npm ERR! 404 tarball, folder, http url, or git url.

npm ERR! A complete log of this run can be found in:
npm ERR!    /logs/2020-12-15T14_00_53_858Z-debug.log

Adding a private npm registry

The easiest way to add FontAwesomes private npm registry is with a .npmrc that is located in your project root. Create the file and add the following two lines:

@fortawesome:registry=https://npm.fontawesome.com/
//npm.fontawesome.com/:_authToken='YOUR ACCESS TOKEN'

If you now run npm install @fortawesome/fontawesome-pro you're getting the exact result you're looking for.

> @fortawesome/fontawesome-pro@5.15.1 postinstall /node_modules/@fortawesome/fontawesome-pro
> node attribution.js

Font Awesome Pro 5.15.1 by @fontawesome - https://fontawesome.com
License - https://fontawesome.com/license (Commercial License)

+ @fortawesome/fontawesome-pro@5.15.1
added 1 package from 6 contributors and audited 1 package in 8.285s
found 0 vulnerabilities

Securing your access token

In general, it is a bad practice to have any secret such as access tokens, private keys, ... in your code and repository. Instead, we're going to replace YOUR ACCESS TOKEN with the environment variable [add link to env var docs] NPM_AUTH_TOKEN_FONTAWESOME that holds your token.

@fortawesome:registry=https://npm.fontawesome.com/
- //npm.fontawesome.com/:_authToken='YOUR ACCESS TOKEN'
+ //npm.fontawesome.com/:_authToken=${NPM_AUTH_TOKEN_FONTAWESOME}

Setting your env vars in WunderPreview

You can find the full guide on environment variables in WunderPreview here.

To set the NPM_AUTH_TOKEN_FONTAWESOME env var in WunderPreview, go to your repository settings scroll down to "Environment Variables" and enter your npm auth token. After saving, they will be made available instantly during runtime.

Screenshot of env var settings in repository settings
Environment variables settings in WunderPreview

To expose this env var during build time there is just one more step:

Making the env var available during build time

To access the env vars during build time we need to consume them in our Dockerfile by simply using ARG and then expose it as an env var via ENV.

FROM node

# used in .npmrc:
ARG NPM_AUTH_TOKEN_FONTAWESOME
ENV NPM_AUTH_TOKEN_FONTAWESOME=$NPM_AUTH_TOKEN_FONTAWESOME

RUN npm install
...

Commit & push your changes and let WunderPreview build a new preview. You'll now see that @fortawesome/fontawesome-pro can be installed and does not break your previews.

What we have learned

You now know how to

  • use private npm registries
  • add env vars in WunderPreview
  • consume build args in your Dockerfile

Do you have any questions or remarks? Just send us an email to hi@wunderstack.io. We are happy to hear from you!

Keep things moving with automated previews.

Screenshot of WunderPreview Dashboard