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

# Private npm Registry (.npmrc)

> Configure a custom .npmrc file to authenticate with private npm registries during cloud agent sessions.

## Overview

If your project depends on packages from a private npm registry, you can provide a custom `.npmrc` that Stably writes to the repository root before dependency installation in cloud agent sessions.

The `.npmrc` supports `${VAR_NAME}` substitution — reference tokens stored as [environment variables](/stably2/environments) instead of hardcoding secrets. The resolved content is never logged.

All major package managers (npm, pnpm, yarn, bun) respect the project-level `.npmrc`.

***

## Configuration

When linking your repository in the Stably dashboard, paste your `.npmrc` content into the **`.npmrc`** text area, using `${VAR_NAME}` placeholders for secrets.

Stably provides built-in templates for common registries:

| Registry            | Template                                                                                                                                      |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **npm**             | `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`                                                                                               |
| **GitHub Packages** | `@scope:registry=https://npm.pkg.github.com` + `//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}`                                             |
| **Sonatype Nexus**  | `@scope:registry=https://nexus.example.com/repository/npm-private/` + `//nexus.example.com/repository/npm-private/:_authToken=${NEXUS_TOKEN}` |

Replace `@scope` with your npm scope (e.g., `@mycompany`).

***

## Example: GitHub Packages with a PAT

### 1. Create a GitHub Personal Access Token

Go to [github.com/settings/tokens](https://github.com/settings/tokens), generate a **classic** token with the **`read:packages`** scope, and copy it.

### 2. Store the token in Stably

In the Stably dashboard, go to **Environments**, select your environment, and add a variable named `GH_PAT` with the token as the value. Mark it as **Sensitive**.

### 3. Configure the .npmrc

In your [repository settings](https://app.stably.ai/settings?tab=git), paste into the `.npmrc` text area:

```ini theme={null}
@your-org:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GH_PAT}
```

Replace `@your-org` with your GitHub organization or username scope.

When a cloud session starts, Stably resolves `${GH_PAT}` from your environment, writes the `.npmrc`, and your package manager authenticates with GitHub Packages during install.

***

## Related

<CardGroup cols={2}>
  <Card title="Environments" icon="key" href="/stably2/environments">
    Create and manage environment variables for your projects
  </Card>

  <Card title="Setup Script" icon="terminal" href="/stably2/setup-script">
    Run custom scripts during cloud session initialization
  </Card>
</CardGroup>