Once you have signed up for a Gemfury account and uploaded a few npm packages, you can install them via command-line or as package.json dependencies.

Setting up your npm registry

To start using your npm registry, you will need to update your npm config:

npm config set registry https://npm.fury.io/USERNAME/

It is important to include a trailing slash in the registry URL, otherwise npm may have trouble connecting to your Gemfury registry.

At this point, you can start to npm install public packages from your account.

To publish and install private packages, you will first authenticate with your Gemfury credentials:

npm login

Once logged in, you can npm publish and npm install private packages from your Gemfury account.

Combining Gemfury with default index

The npm.fury.io repository only enables access to your packages, however, we also offer a blended-index proxy to allow you to install packages from both your Gemfury account and from the public index:

https://npm-proxy.fury.io/USERNAME/

You can activate the blended repo by running these commands:

npm config set registry https://npm-proxy.fury.io/USERNAME/
npm login

It is important to include a trailing slash in the registry URL, otherwise npm may have trouble connecting to your Gemfury registry.

When you install an individual package or a project’s dependencies, if available, this endpoint will serve named packages from your Gemfury account, and falling back on the public index (https://registry.npmjs.org/) for those that are not found.

Building and uploading packages

There are a few guides on the web about creating an npm package - they will work with Gemfury.

Once you have configured npm to work with your private registry and prepared your package, just publish as usual:

npm publish

Or you can use any of the other upload method, such as Git:

git remote add fury https://git.fury.io/username/pkg-name.git
git push fury master

Install packages via command-line

You can use your Registry URL to install packages individually. First, you need to configure npm authentication to enable access to your private packages.

To configure it manually, append the following line to ~/.npmrc:

//npm.fury.io/USERNAME/:_authToken=SECRET-TOKEN

Or use the CLI and enter your Gemfury credentials:

npm login --registry https://npm.fury.io/USERNAME/

You can now install individual packages by running:

npm install my-module --registry https://npm.fury.io/USERNAME/

Install packages via package.json

Once you have configured npm to use your Gemfury account, specifying dependencies and installing packages from package.json is the same as usual.

Remember to use the blended index to seamlessly mix public and private dependencies in your project.

Working with scoped packages

Uploading a scoped package to Gemfury is no different from a regular package. Once you’ve updated its package.json with the scoped name, you can push the package via the Dashboard, cURL, CLI or Git.

{
  "name": "@myorg/js-example"
}

Use the --scope option to configure a Gemfury-backed scope:

npm config set registry https://npm.fury.io/USERNAME/ --scope=@myorg
npm login --scope=@myorg

Once you’re logged-in, you can publish and install packages from your scope:

npm install @myorg/js-example

And include them in your project’s dependencies:

{
  "dependencies": {
    "@myorg/js-example": ">=1.0.0"
  }
}

Keep your privates private

To keep up with the best practices, it’s important to keep your Gemfury credentials out of your source code, particularly your project’s .npmrc, package.json, and package-lock.json files. Furthermore, we encourage each developer to use only individual credentials to access shared accounts.

Rather than explicitly placing your authentication token in the .npmrc configuration file, you can use an environment variable as a placeholder, and npm will expand the variable at runtime.

In this case, you will append the following to your .npmrc:

//npm-proxy.fury.io/USERNAME/:_authToken=${FURY_AUTH}

You can then authenticate via the environment when running npm commands:

FURY_AUTH="5f..03C" npm install

Thus, in production, you can use the facilities of your platform to define FURY_AUTH in a secure manner. While in development, each developer can set FURY_AUTH to their personal token in their shell startup file.

Fixing “Error: CERT_UNTRUSTED”

When installing from your Gemfury npm registry, you may see the following error:

npm ERR! Error: CERT_UNTRUSTED

This happens because legacy versions of npm trust only their own self-signed certificate. So despite being valid, our SSL certificate may raise this error by npm. To work around this issue, please run the following command:

npm config set ca ""

To keep your Gemfury registry secure, please do not disable SSL by switching to http://