How to use the JS Registry with npm

This section discusses the compatibility of the JS Registry to the Node package manager (npm) .

Introduction

The package tree REST interface of the JS Registry implements the CommonJS Package Registry specification and is therefore compatible to the npm-install command line tool.

npm

npm is a tool used to install JavaScript packages hosted in the Node package registry on a local machine. It is a command line tool, which is distributed together with Node.js .

A typical command is npm install, which installs a package into a local folder. For more details, see npm-install .

# installs a package into the current folder
$ npm install <packagename>

# for example install the latest map package
# this creates a "node_modules" folder in the current directory
# the map package is downloaded and extracted into this "node_modules" folder
$ npm install map


# you can define the exact version of the package to install
$ npm install map@3.1.0

The JS Registry can be used by adding the --registry flag to the npm command.

# install the map package from the js registry
$ npm --registry=http://localhost:8080/resources/jsregistry/root install map

# install the map package from the js registry (specific version here)
$ npm --registry=http://localhost:8080/resources/jsregistry/root install map@3.1.0

Prerequisites

The npm install command expects a dist section with tarball information inside a package info response of the registry to download and install the JavaScript files locally.

Request - generate a dist section by query parameter
GET /resources/jsregistry/root/<name>/<version>?dist=true
Response
// GET /resources/jsregistry/root/aceeditor/3.1.0-SNAPSHOT?dist=true
{
    "name": "aceeditor",
    "ACE-VERSION": "1.1.1",
    "version": "3.1.0-SNAPSHOT",
    ...

    "_id": "aceeditor@3.1.0-SNAPSHOT",
    "location": "http:\/\/localhost:8080\/js\/bundles\/base\/aceeditor",
    "dist": {
        "zip": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/aceeditor\/-\/aceeditor@3.1.0-SNAPSHOT.zip",
        "zip_shasum": "f20f339bb12ae41ce66c5fd1b8df43d6402cc01f",
        "tarball": "http:\/\/localhost:8080\/resources\/jsregistry\/root\/aceeditor\/-\/aceeditor@3.1.0-SNAPSHOT.tgz",
        "shasum": "8fc096371f88a6aa7f2616db03d9ce4c5c025efe"
    }
}
Query Parameter
Name Default Description

dist

false

Flag which indicates that the distribution information should be appended to the package info

The dist parameter is set to true if the npm command line tool is recognized as requestor.

This distribution info is only generated if the configuration option jsregistry.distribution.enabled is set to true.

When do packages have associated distribution files?

  • All uploaded packages have distribution files

  • Packages provided inside JAR files and imported by the classpath scanner have no distribution information

  • Packages imported with the directory scanner have distribution information in the following cases

    1. the configuration option jsregistry.directoryscanner.buildDistributionFiles is enabled

    2. the configuration option jsregistry.directoryscanner.registerAsFileLocation is disabled

    3. the configuration option jsregistry.directoryscanner.registerAsFileLocation is enabled and the scanned package contains a dist folder containing a distribution zip file <name>@<version>.zip

Best Practice

If npm is used to set up the resources of a "JavaScript-only" project, we recommend to first build a package.json for the project like this:

{
    "name" : "myproject",
    "version" : "1.0.0",
    "dependencies" : {
        // list all dependencies
        "map": "3.1.0-SNAPSHOT",
        "coordinatetransformer": "3.1.0-SNAPSHOT",
        "geometryservice": "3.1.0-SNAPSHOT"
    }
}

Afterwards, use npm install inside the folder where the package.json is located to install the packages:

# install all dependencies into the directory "node_modules"
$ npm --registry=http://localhost:8080/resources/jsregistry/root install
npm creates subdirectories named "node_modules" inside the downloaded packages if a package is not listed as a project dependency of the main project but required by a dependency. Adding the package to the project dependencies might remove the subfolders.