NPM Compatibility

This section discusses the compatibility of the JS Registry to the node package manager (NPM).

Introduction

The node package manager is a tool used to install JavaScript packages hosted in the node package registry into a local machine. It is a command line tool, which is distributed together with nodejs .

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


# it is possible to define the exact version of the package to install
npm install map@3.1.0

The package tree (/root) interface of the JS Registry implements the Common JS Package Registry specification and is therefore compatible to the npm install command line tool.

The js registry can be used by adding the --registry flag to the npm command line.

# 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 line expects a dist section with tarball information inside a package info response of the registry to download and install the JavaScript files locally.

Request - Sample to generate a dist section by query parameter
-------
GET /resources/jsregistry/root/<name>/<version>?dist=true

for example

GET /resources/jsregistry/root/aceeditor/3.1.0-SNAPSHOT?dist=true

Response - With dist section
--------
{
	"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 is appended to the package info

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

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

When have packages 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, it is recommended to first build a package.json for the project like:

{
	"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 sub "node_modules" directories inside the downloaded packages if a package is not listed inside the dependencies of the main project but required by a dependency. Adding the package to the project dependencies list might remove this sub folder.