How to Point npm at Chainsaw

Beginner 15 minutes Developers / DevOps Engineers Getting Started

Configure npm (and Bun) to install through your Chainsaw proxy via .npmrc, global config, and authentication.

Overview

Point npm at your Chainsaw instance so every install passes through the firewall for scanning, policy checks, and audit logging. This page covers the project-level .npmrc, global configuration, and authentication.

Examples below use chain305.com, the hosted service. If you self-host, replace the host in each snippet with your own, and swap CLIENT_ID / CLIENT_SECRET for credentials issued from the Access page in the Chainsaw dashboard. The @default segment is the org slug — new single-tenant installs default to default; confirm yours under Settings → Organization → Slug, or copy it from the @<slug> segment of any generated config snippet under Settings → Client Credentials → New. Legacy non-org-scoped URLs (/repository/npmjs/) return HTTP 400 with error CHW-4314.

Prerequisites

  • A running Chainsaw instance (see Tutorial 01)
  • Client credentials (Client ID and Secret)
  • npm installed

Clear Local Caches (First-Time Setup)

Most package managers skip downloading packages that already exist in local caches or node_modules. Clear them once so the first install passes through the firewall:

rm -rf node_modules package-lock.json
npm cache clean --force

Project-Level (.npmrc)

registry=https://chain305.com/chainproxy/repository/@default/npmjs/
//chain305.com/chainproxy/repository/@default/npmjs/:_auth=<base64(CLIENT_ID:CLIENT_SECRET)>
//chain305.com/chainproxy/repository/@default/npmjs/:always-auth=true

Generate the base64 token with printf '%s' "$CLIENT_ID:$CLIENT_SECRET" | base64. The _auth field expects the encoded form per the .npmrc spec — passing the raw CLIENT_ID:CLIENT_SECRET literal makes npm ship installs with no Authorization header and the proxy returns HTTP 401. always-auth=true ensures the credential rides on tarball fetches too, not just metadata lookups.

Global Configuration

npm config set registry https://chain305.com/chainproxy/repository/@default/npmjs/
npm login --registry=https://chain305.com/chainproxy/repository/@default/npmjs/

Bun

Bun reads .npmrc as a fallback when no bunfig.toml registry is set. The configuration above applies verbatim — Bun honors the same registry=, _auth=, and always-auth=true fields. If you also have a bunfig.toml, set:

[install.registry]
url = "https://chain305.com/chainproxy/repository/@default/npmjs/"
token = "<base64(CLIENT_ID:CLIENT_SECRET)>"

Verify

npm install lodash

Then run chainsaw doctor verify-hook from the same shell to confirm the install genuinely reached the proxy, and check the Traffic page in the dashboard.

Next Steps