npm dependencies

Site admins can sync npm packages from any npm registry, including open source code from npmjs.com or a private registry such as Verdaccio, to their Sourcegraph instance so that users can search and navigate the repositories.

To add npm dependencies to Sourcegraph you need to setup an npm dependencies code host:

  1. As site admin: go to Site admin > Global settings and enable the experimental feature by adding: {"experimentalFeatures": {"npmPackages": "enabled"} }
  2. As site admin: go to Site admin > Manage code hosts
  3. Select npm Dependencies.
  4. Configure the connection by following the instructions above the text field. Additional fields can be added using Cmd/Ctrl+Space for auto-completion. See the configuration documentation below.
  5. Press Add repositories.

Repository syncing

There are three ways to sync npm dependency repositories.

  • SCIP (recommended): run scip-typescript on your JavaScript/TypeScript codebase and upload the generated index to Sourcegraph using the src-cli command src code-intel upload. Sourcegraph automatically synchronizes npm dependency repositories based on the dependencies that are discovered by scip-typescript.
  • Code host configuration: manually list dependencies in the "dependencies" section of the JSON configuration when creating the npm dependency code host. This method can be useful to verify that the credentials are picked up correctly without having to upload an index.

Credentials

Use the "credentials" section of the JSON configuration to provide an access token for your private npm registry. See the official npm documentation for more details about how to create, list and view npm access tokens.

Rate limiting

By default, requests to the npm registry will be rate-limited based on a default internal limit which complies with the documented acceptable use policy of registry.npmjs.org (i.e. max 5 million requests per month).

"rateLimit": {
  "enabled": true,
  "requestsPerHour": 3000.0
}

where the requestsPerHour field is set based on your requirements.

Not recommended: Rate-limiting can be turned off entirely as well. This increases the risk of overloading the code host.

"rateLimit": {
  "enabled": false
}

Configuration

npm dependencies code host connections support the following configuration options, which are specified in the JSON editor in the site admin "Manage code hosts" area.

admin/external_service/npm-packages.schema.json 

{
	// Access token for logging into the npm registry.
	"credentials": "",
	// Other example values:
	// - "CRs5VaTVbR7pBPcVpaxwQeafrYOId7IdVUiZCkFCqnw="

	// An array of "(@scope/)?packageName@version" strings specifying which npm packages to mirror on Sourcegraph.
	"dependencies": null,
	// Other example values:
	// - ["[email protected]"]
	// - [
	//     "react@latest",
	//     "@types/[email protected]"
	//   ]

	// Rate limit applied when making background API requests to the npm registry.
	"rateLimit": {
		"enabled": true,
		"requestsPerHour": 6000
	},

	// The URL at which the npm registry can be found.
	"registry": "https://registry.npmjs.org"
	// Other example values:
	// - "https://npm-registry.mycompany.com"
}