> ## Documentation Index
> Fetch the complete documentation index at: https://docs.root.io/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript - npm, pnpm, yarn

> Configure npm, pnpm, and yarn to use Root Library Catalog for secure JavaScript packages.

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.

```bash theme={null}
# 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/
```

For macOS Intel and Windows, see the [full installation instructions](/rlc/patcher#installation).

Then set your API key:

```bash theme={null}
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 |

<Note>
  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.
</Note>

## Authentication

All package managers use the same auth setup. The registry requires base64-encoded credentials:

```bash theme={null}
# 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
```

This writes to your project-level `.npmrc`.

***

## npm

### Configure auth

```bash theme={null}
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:

```bash theme={null}
npm remove requests
```

Add to `package.json`:

```json theme={null}
{
  "dependencies": {
    "axios": "npm:@rootio/axios@1.6.0"
  },
  "overrides": {
    "axios": "npm:@rootio/axios@1.6.0"
  }
}
```

### Install

```bash theme={null}
npm install
```

***

## pnpm

### Configure auth

Same as npm:

```bash theme={null}
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

```bash theme={null}
pnpm remove axios
```

Add to `package.json`:

```json theme={null}
{
  "dependencies": {
    "axios": "npm:@rootio/axios@1.6.0"
  },
  "pnpm": {
    "overrides": {
      "axios": "npm:@rootio/axios@1.6.0"
    }
  }
}
```

### Install

```bash theme={null}
pnpm install
```

***

## yarn

### Yarn 1 (Classic)

**Configure auth** (same as npm):

```bash theme={null}
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:**

```bash theme={null}
yarn remove axios
```

```json theme={null}
{
  "resolutions": {
    "axios": "npm:@rootio/axios@1.6.0"
  }
}
```

```bash theme={null}
yarn install
```

### Yarn 3+ (Berry)

**Configure auth:**

```bash theme={null}
yarn config set npmScopes.rootio.npmRegistryServer https://pkg.root.io/npm/ &&
yarn config set 'npmRegistries["//pkg.root.io/npm/"].npmAuthIdent' 'root:YOUR_ROOT_TOKEN'
```

**Update package.json:**

```bash theme={null}
yarn remove axios
```

```json theme={null}
{
  "resolutions": {
    "axios": "npm:@rootio/axios@1.6.0"
  }
}
```

```bash theme={null}
yarn install
```

***

## 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            |