Working with NPM

Publish NPM Package

1. Configure your scope to use OneDev registry:

   $ npm config set @<scope>:registry https://onedev.example.com/<project path>/~npm/

   Param	Explanation
   <scope>	scope of your package
   <project path>	path of a project with package management enabled

2. Configure auth token of the registry:

   $ npm config set -- '//onedev.example.com/<project path>/~npm/:_authToken' "<onedev_access_token>"

   Param	Explanation
   <project path>	same as above
   <onedev_access_token>	OneDev access token with package write permission over the project

3. Publish the package from the directory containing its package.json:

   $ npm publish

4. For CI/CD job, run below to publish package via command step:

   # Use @@ to reference scope in job commands to avoid being interpreted as variable
   npm config set @@<scope>:registry https://onedev.example.com/<project path>/~npm/
   
   # Use job token to tell OneDev the build publishing the package
   # Job secret 'access-token' should be defined in project build setting as an access token with package write permission
   npm config set -- '//onedev.example.com/<project path>/~npm/:_authToken' "@job_token@:@secret:access-token@"
   
   npm publish

   Param	Explanation
   <scope>	same as above
   <project path>	same as above

Consume Published NPM Package

Open Packages in the project and select the published version. The detail page provides registry configuration and installation commands. Configure a token with package read permission, then install the package in a separate project:

npm install @<scope>/<package-name>@<version>

Use a project-local .npmrc or a dedicated npm user configuration for registry credentials, and keep token-bearing files out of source control. The registry URL must be reachable from the machine or container running npm. When testing a host server from Docker Desktop, host.docker.internal can reach the host; configure the server's advertised URL appropriately for package download links too.

A package published using @job_token@:<access-token> is attributed to its publishing build, as shown above. Versions published directly from a terminal are attributed to the token owner.