Root Library Catalog serves patched JavaScript packages under the @rootio/ scope. Rather than replacing your registry globally, you add an override or resolution that maps the vulnerable package to its Root-patched equivalent at pkg.root.io/npm/.
Prerequisites
The Root Patcher CLI (rootio_patcher) is required to pull Root-secured packages into your environment. Install it before configuring your package manager.
# macOS (Apple Silicon)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_darwin_arm64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/
# Linux (x86_64)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_linux_x86_64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/
export ROOTIO_API_KEY="your-api-key-here"
Which package manager should I use?
Root supports npm, pnpm, and both Yarn generations. The auth setup is shared across all of them; the difference is in how each package manager applies the @rootio/ override.
| Package manager | Best for |
|---|
| npm | Default Node.js projects, no special tooling required |
| pnpm | Monorepos, projects prioritizing disk efficiency, faster installs |
| Yarn 1 (Classic) | Existing Yarn 1 projects using resolutions |
| Yarn 3+ (Berry) | Projects already on Berry - auth is configured differently than Yarn 1 |
The overrides / resolutions / pnpm.overrides field in package.json is what tells your package manager to resolve the original package name to Root’s patched @rootio/ equivalent. This is required for all JavaScript package managers.
Authentication
All package managers use the same auth setup. The registry requires base64-encoded credentials:
# This sets the registry and encodes your credentials as base64(root:YOUR_TOKEN)
npm config set registry https://pkg.root.io/npm/ --location=project &&
npm config set //pkg.root.io/npm/:_authToken YOUR_ROOT_TOKEN --location=project
.npmrc.
npm
npm config set registry https://pkg.root.io/npm/ --location=project &&
npm config set //pkg.root.io/npm/:_authToken YOUR_ROOT_TOKEN --location=project
Update package.json
Remove the original package and add the Root-patched version using @rootio/ scope:
Add to package.json:
{
"dependencies": {
"axios": "npm:@rootio/axios@1.6.0"
},
"overrides": {
"axios": "npm:@rootio/axios@1.6.0"
}
}
Install
pnpm
Same as npm:
npm config set registry https://pkg.root.io/npm/ --location=project &&
npm config set //pkg.root.io/npm/:_authToken YOUR_ROOT_TOKEN --location=project
Update package.json
Add to package.json:
{
"dependencies": {
"axios": "npm:@rootio/axios@1.6.0"
},
"pnpm": {
"overrides": {
"axios": "npm:@rootio/axios@1.6.0"
}
}
}
Install
yarn
Yarn 1 (Classic)
Configure auth (same as npm):
npm config set registry https://pkg.root.io/npm/ --location=project &&
npm config set //pkg.root.io/npm/:_authToken YOUR_ROOT_TOKEN --location=project
{
"resolutions": {
"axios": "npm:@rootio/axios@1.6.0"
}
}
Yarn 3+ (Berry)
Configure auth:
yarn config set npmScopes.rootio.npmRegistryServer https://pkg.root.io/npm/ &&
yarn config set 'npmRegistries["//pkg.root.io/npm/"].npmAuthIdent' 'root:YOUR_ROOT_TOKEN'
{
"resolutions": {
"axios": "npm:@rootio/axios@1.6.0"
}
}
How @rootio/ packages work
Root publishes patched packages under the @rootio/ npm scope. The overrides / resolutions / pnpm.overrides fields in package.json tell your package manager to resolve the original package name to the Root-patched equivalent - no changes to your import statements required.
Troubleshooting
| Issue | Solution |
|---|
401 Unauthorized | Verify your token: npm config get //pkg.root.io/npm/:_authToken |
| Package not found | Confirm @rootio/ scoped package exists for your version |
integrity check failures | Expected - Root patches modify package contents |
| Overrides not applying | Ensure both dependencies and overrides are updated |
