Private Package Registry

Fusebit provides a private package registry for each customer, which can be used to share code between different integrations in that account.

Each private registry is only accessible by users of that account with the registry:get permission, and can be used to store and version internal artifacts that are used as part of the Fusebit integration development and deployment process. All of the standard tools such as npm, yarn, and so forth are supported.

In order to handle multiple registries, these tools make use of package scope. In the Javascript ecosystem, a scope is an arbitrary string starting with an @ that prefixes the package name, separated with a /. For example, the Fusebit CLI, found in the public registry as @fusebit/cli, resides in the @fusebit scope.

Each private registry provided by Fusebit supports one or more scopes that it will serve packages for. As an example, a private registry might be configured to be authoritative for the @private scope. This would allow engineers to deploy packages named @private/feature to that private registry for consumption only by other Fusebit integrations and Fusebit users with the registry:get permission.

Building a private package

You have been developing a few Fusebit integrations, and have identified a set of utility functions that are in common use. Rather than copying the code into every individual Fusebit integration, you’d like to create a single package that contains all of that code, that you can then refer to in each Fusebit integration as you create it.

All of the utility functions are collected in a single file in the utility/ directory, along with a basic package.json file:

// utility/index.js
    
exports.welcomeMessage = () => 'Hello World!';

And package.json:

{
    "name": "@private/utility",
    "version": "1.0.0",
    "main": "index.js"
}

Set up the Fusebit private registry

The first step is to configure the internal private registry so that it is authoritative for your packages. Keeping things simple, you decide to use the @private scope for all of your internal packages. You can change it in the future if you need to, or even add additional scopes for different parts of the product.

Adding the scope to the private registry configuration is easy. You use the fuse command line tool:

$ fuse npm registry scope set @private
    Mapped        │  @private, @fusebit-int
    Scopes        │
    
$

This reports back that both the @private scope as well as a Fusebit-managed @fusebit-int scope are configured on your registry. All scopes, except for ones that start with @fuse which are reserved for Fusebit-managed scopes, are available for use.

Configure your local npm client

With the scope configured, you need to tell your local npm client to use the private registry for those packages:

$ fuse npm login
    Login         │  Logged into npm for the following scopes:
    Successful    │
                  │  @private, @fusebit-int
                  │
                  │  Packages that within those scopes are accessible via npm
                  │  install and published via npm publish.
    
$

The fuse npm login command is equivalent to npm login and populates a ~/.npmrc file with the appropriate configuration and security tokens to communicate with the private registry.

📘

The token created by fuse npm login is only valid for a limited length of time, usually around 2 hours. If a npm command fails due to authentication, call fuse npm login again to refresh the token.

Now that npm is configured, commands like npm install @private/utility will query the private registry for that package. In fact, you can use all of the normal npm, yarn, or similar commands to manage packages, except for search, for which you will need to use fuse npm search.

Publishing your first package

Now that the private registry and your local client are configured, it’s time to publish the utility package.

Just like any other Javascript package, you can publish to the private registry using npm publish:

$ npm publish
    npm notice
    npm notice 📦  @private/[email protected]
    npm notice === Tarball Contents ===
    npm notice 0   index.js
    npm notice 76B package.json
    npm notice === Tarball Details ===
    npm notice name:          @private/utility
    npm notice version:       1.0.0
    npm notice package size:  186 B
    npm notice unpacked size: 76 B
    npm notice shasum:        1492aa9c7af2c8da3d97b20cc8bf2dd4897d7987
    npm notice integrity:     sha512-RudYIVkV/4GyX[...]MILVPGMuJsNmg==
    npm notice total files:   2
    npm notice
    + @private/[email protected]
    
$

👍

Congratulations!

You’ve published the @private/utility package to the private registry! You can see it by using the fuse npm search tool:

$ fuse npm search utility
    NAME                      | DESCRIPTION          | AUTHOR          | DATE       | VERSION  | KEYWORDS
    @private/utility          |                      |                 | 2020-11-22 |          |
    
$

If you need to increase the version, you can change the version number in the package.json file and publish it again using npm publish.

Using your new @private/utility package

Making use of the new package is just like using any other npm package. Download one of the integration you were previously using the utility functions within using fuse integration get -d .. Then, add the package as a dependency:

$ npm install @private/[email protected]^1.0.0
    + @private/[email protected]
    added 1 package from 1 contributor and audited 1 package in 0.43s
    found 0 vulnerabilities
    
$

You could also install the dependency in the package.json directly:

{
    "name": "@private/utility",
    "version": "1.0.0",
    "main": "index.js",
    "dependencies": {
      "@private/utility": "^1.0.0"
      }
}

With the package installed, you can import in the source file similar to other Javascript packages:

`const utility = require('@private/utility');`

Once you’ve added this to your integration, deploy it again using fuse integration deploy -d . The integration will be populated with the package in @private/utility from the private registry.

Upgrading a deployed package

Once a package is in use in an integration, it can become necessary to upgrade it as new features are added. With the new version (1.0.1) already deployed to the private registry using npm publish, it becomes a simple matter to direct the integration to re-evaluate their semver control string:

`$ fuse integration rebuild -b customer featurefunction`

The rebuild process causes that particular integration to re-evaluate it’s semver control string - currently ^1.0.0 and find a new matching version, in this case 1.0.1. This allows you to control the roll-out of a new feature to minimize risk, and remove the new package if it turns out not to have the behavior desired.

If you want to upgrade a larger number of integrations simultaneously, you can use the --search option to find integrations that match a set of tag criteria:

$ fuse integrations rebuild -s tag.company=intel

This will search for all integrations that have the company tag equal to intel, and trigger each one to re-evaluate it’s semver control string.


Did this page help you?