---
component: npm
version: "4.0"
slug: npm/index
canonical_url: "https://docs.gradle.com/develocity/npm/4.0/"
title: "Getting Started With Develocity for npm Users"
description: "How to get started with Develocity for npm."
keywords: []
status: current
---
> Canonical:
# Getting Started With Develocity for npm Users
This guide covers how to get started with Develocity, with topics such as strategies for incrementally introducing Build Scan usage, and key Build Scan features for improving your development productivity.
Develocity provides [Build Scan](#build_scan), a permanent and shareable record of an executed build that allows collaborative troubleshooting and optimization.
> [!NOTE]
> npm support isn’t enabled by default with Develocity. If you want to use npm with Develocity, please contact your customer success representative.
* * *
## Installation
This guide doesn’t cover installation of Develocity. Consult one of the following installation manuals for help with installation:
* [Self-Hosted Kubernetes Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/kubernetes-installation/)
* [Self-Hosted Standalone Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/standalone-installation/)
* [Amazon EKS Kubernetes Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/aws/aws-eks-cluster/)
* [Amazon EC2 Standalone Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/aws/aws-ec2-standalone/)
* [Azure AKS Kubernetes Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/azure/azure-aks-cluster/)
* [Azure VM Standalone Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/azure/azure-vm-standalone/)
* [Google GKE Kubernetes Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/google-cloud/gke-kubernetes/)
* [Google Compute Engine Standalone Installation Guide](https://docs.gradle.com/develocity/2026.1/installation/google-cloud/gce-standalone/)
The remainder of this guide will assume that your installation has a public hostname of `develocity.example.com` and has enabled HTTPS.
### Develocity npm Agent
To use Build Scans, you must apply the [Develocity npm agent](https://docs.gradle.com/develocity/npm/4.0/npm-agent/) to your project.
#### Setup
##### Install the Agent
The Develocity npm agent is an npm package available on the npm registry. There are two ways to install the agent.
1. Installing the agent globally in a well-known folder. This approach makes it possible to use the agent in any npm project on a machine without adding it as a dependency to each one. A key advantage is the ability to capture a Build Scan even when a project’s dependencies haven’t yet been installed, such as when running `npm install` on a fresh checkout. This is the most convenient and **recommended** way to install the agent. See [Global installation in a well-known folder](#global_installation_well_known_folder) for details.
2. Installing the agent as a local dependency. Unlike the global installation, this approach requires the agent to be installed in each project where you want to use it. It creates the inconvenience of having to set and unset the `NODE_OPTIONS` environment variable depending on whether the agent is available in the project or not. The significant disadvantage of the local installation, that it doesn’t allow capturing a Build Scan until the project’s dependencies have been installed, such as when running `npm install` on a fresh checkout. See [Local Installation](#local_installation) for details.
##### Recommended: Global Installation in a Well-Known Folder
> [!WARNING]
> This approach won’t work if Node.js is run with the --no-global-search-paths option.
Node.js loads packages from several well-known [global folders](https://nodejs.org/docs/latest-v22.x/api/modules.html#loading-from-the-global-folders). Placing the agent in one of these folders allows Node.js to find and load the agent for all Node.js processes on the machine, including npm invocations.
To install the agent into any of these folders, for example `~/.node_libraries`, run the following command:
```shell
npm exec -y -- pacote extract @gradle-tech/develocity-agent@4.0.0 ~/.node_libraries/@gradle-tech/develocity-agent
```
> [!NOTE]
> If the installation into one of the global folders isn’t possible, the agent can be installed into an arbitrary folder on the machine. To install the agent into a folder such as ~/.develocity/npm-agent, run the following command: Then set the NODE\_PATH environment variable to point to the folder where the agent was installed:
##### Local Installation
If the [global installation](#global_installation_well_known_folder) doesn’t work with your setup, you can install the agent locally in your project by running the following command:
```shell
npm install --save-dev @gradle-tech/develocity-agent@4.0.0
```
#### Prepare the Agent for Use
The agent is a regular Node.js module. In order for it to instrument npm invocations, it needs to be preloaded, [using the `-r` option of Node.js](https://nodejs.org/docs/latest-v22.x/api/cli.html#-r---require-module). In order for this flag to be passed to the npm process, it needs to be set in the [`NODE_OPTIONS` environment variable](https://nodejs.org/docs/latest-v22.x/api/cli.html#node_optionsoptions).
##### Agent Installed Globally
If you installed the agent globally, as described in the [Global installation in a well-known folder](#global_installation_well_known_folder) section, you only need to set the `NODE_OPTIONS` environment variable using the following command:
```shell
export NODE_OPTIONS='-r @gradle-tech/develocity-agent/preload'
```
##### Agent Installed Locally
If you installed the agent as a project dependency, as described in the [Local Installation](#local_installation) section, it requires the `NODE_OPTIONS` environment variable to be set and unset manually depending on the availability of the agent in the project (or in the system at large for that matter, since `NODE_OPTIONS` applies to _any_ Node.js process).
As this can be tedious, error-prone, and lead to unexpected failures, we provide a separate [Develocity agent loader](https://www.npmjs.com/package/@gradle-tech/develocity-agent-loader) package to simplify the process of loading the agent.
###### Develocity Agent Loader
The Develocity agent loader is a small package whose sole purpose is to load the agent if it’s currently available in the project, or silently ignore if it’s not.
To install it, use the command line below.
```shell
npm install --global @gradle-tech/develocity-agent-loader
```
To ensure that the agent is preloaded, set the `NODE_OPTIONS` environment variable as follows:
```shell
export NODE_OPTIONS="-r $(npm root -g)/@gradle-tech/develocity-agent-loader"
```
From now on, the Develocity npm agent will be automatically preloaded if it has been installed for the current project.
> [!TIP]
> By default, the agent loader will simply ignore any error in loading the agent (which usually simply means that the agent itself isn’t installed for the current project). If you expect the agent to be loaded, but it’s not, you can set the DEVELOCITY\_AGENT\_LOADER\_DEBUG environment to true to make the loader print the error.
###### Managing `NODE_OPTIONS` Manually
There are situations, such as CI, where managing `NODE_OPTIONS` manually is just as convenient as depending on the agent loader as a global package. In these cases, or if for other reasons you cannot use the agent loader, you can load the agent directly.
To ensure that the agent is preloaded, use the `NODE_OPTIONS` environment variable as such:
```shell
export NODE_OPTIONS='-r @gradle-tech/develocity-agent/preload'
```
Note that the agent will be preloaded for all invocations of Node.js. This can be inconvenient when working on local development environments, as `NODE_OPTIONS` needs to be set and unset depending on the availability of the agent in the project to avoid invocations of Node.js to fail. If you are in a situation where using the agent loader is unfeasible and need to manage `NODE_OPTIONS` manually, you might want to consider tooling to do that for you, such as [dotenvx](https://dotenvx.com/) or [direnv](https://direnv.net/).
#### Configuration
To configure the agent, create a file called `develocity.config.js` or `develocity.config.cjs` in the root of your project.
```javascript
module.exports = {
server: {
url: 'https://develocity.example.com',
},
}
```
> [!NOTE]
> Configuration files using ESM or TypeScript aren’t supported.
This is the minimum configuration required to publish a Build Scan. Publishing a Build Scan to [Develocity at gradle.com](https://gradle.com/scans/gradle/) isn’t supported.
Alternatively, you can use environment variables to configure the agent. Use `DEVELOCITY_URL` to set the Develocity server URL:
```shell
export DEVELOCITY_URL=https://develocity.example.com
```
> [!NOTE]
> You might encounter a warning about an untrusted certificate when connecting to Develocity over HTTPS. The ideal solution is for someone to add a valid SSL certificate to the Develocity instance, but we recognize that you may not be able to do that. In this case, set the server.allowUntrustedServer option to true: Alternatively, you can set the DEVELOCITY\_ALLOW\_UNTRUSTED\_SERVER environment variable to true: This is a convenient workaround, but you shouldn’t use it as a long-term solution.
More detailed information about the Develocity npm agent can be found in the [Develocity npm agent user manual](https://docs.gradle.com/develocity/npm/4.0/npm-agent/).
## Build Scan
Build Scans are a significant innovation in software build tooling. Having centralized and shareable records providing fine-grained details and insights of all builds, including local development builds, enables new levels of collaborative debugging and optimization.
### Quick Start
Build Scans are automatically enabled for all builds, when applying the Develocity npm agent. As the build completes, the last lines of output will be similar to:
**Output:**
```
Publishing Build Scan to Develocity...
https://develocity.example.com/s/3z475bz247h5g
```
Follow that link to view your Build Scan.
### Build Scan Highlights
This section calls out a subset of the things that you can do with Build Scans.
#### Find and View any Build Scan
Search through all the captured Build Scans by going to `https://develocity.example.com/scans`.
Build Scan Overview
This view allows searching by various criteria, including top-level project name, username, build outcome, build start time and more. By default, the list is sorted to show the most recent scans first.
Beyond looking for a particular Build Scan, the listing can provide new insights into the actual builds being run at your organization and by your colleagues. You might find occurrences of previously unknown errors with your build, or that the build is taking longer in certain cases than you expected, or that certain build users are executing more goals than they need to and are therefore subjecting themselves to more build time than they need to, and other previously unknown behaviors.
#### Inspect Console Log
The console log will be included in your Build Scan. Use the left navigation menu to visit the `Console Log` section.
Console Log Overview
This section will display all the console log emitted by the instrumented npm process, as well as any process it spawned to perform some particular task (in the example above, `npm test` ran `jest`).
#### Inspect Test Results
If your build executed tests, then their results will be included in your Build Scan. Use the left navigation menu to visit the `Tests` section.
Tests Overview Page
This section shows the results of all the tests that ran during your build, along with their outcome and durations. The results are broken down by _process_, _test file_ and _test_. Select any _test file_ or _test_ to see details about each of their individual executions, in case of test retry. The _total time_ is available for _processes_, _test files_ and _tests_. Generally, it corresponds to the wall clock time that an execution lasted. Refer to [Viewing test results](https://docs.gradle.com/develocity/npm/4.0/npm-agent/#viewing_test_results) for more details.
### Next Steps
#### Custom Tags, Values and Links
Build Scans can be enriched with metadata particular to your environment by [several means](https://docs.gradle.com/develocity/npm/4.0/npm-agent/#extending_build_scans).
Extending your Build Scans with tags, values and links is strongly recommended. In particular:
* VCS information such as commit identifiers, branch names, etc.
* Tags for different types of builds (for example, `CI` vs. `local`)
* Links to CI system record of build for CI builds
This adds useful context to your Build Scans.
### Integrating Your CI Tool
Build Scans are passive with regard to the build process. Enabling Build Scans doesn’t affect the outcome or outputs of your build. As such, it’s generally safe to simply add the necessary configuration to your projects to enable sending Build Scans to your Develocity installation and check it in to version control, enabling it for all users of the build.
The Develocity npm agent won’t cause build failures, even when there is no connection available to the Develocity server when trying to publish.
## Getting Help or Asking Questions
If you are currently using Develocity as part of your trial sign-up or license purchase, you will have received instructions on how to access the priority Develocity support channel. If you have any issues with or questions about Develocity, please raise a support request.
Alternatively, or if you aren’t yet using Develocity, you can use our [contact form](https://gradle.com/contact/).
## Keeping up to Date
Develocity is constantly evolving with regular updates that add new features and capabilities. The monthly [Gradle newsletter](https://newsletter.gradle.org/) is an easy way to stay informed about new releases, features and events.
## Integrating With Gradle
If you run npm through a Gradle task, you might want to use the convenience API we offer through the Gradle Develocity plugin.
Learn more in the [Develocity npm agent user manual](https://docs.gradle.com/develocity/npm/4.0/npm-agent/#gradle_integration).
* * *
If you have any questions or need any assistance contact the Develocity support team or your customer success representative.