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

# Access and authentication

> Installing a private package, in local development and in CI.

`@reviseio/sdk` is published privately to the public npm registry. It is not
installable without a token, and the token is issued to you as part of your
licence.

You do **not** need an npm account, an npm username, or any membership in our
organisation. The token is the whole story.

## What you receive

A read-only access token, scoped to `@reviseio/sdk` alone. It looks like
`npm_` followed by a long string. Treat it as a credential: it grants download
access to licensed software.

<Warning>
  Never commit the token. The `.npmrc` below reads it from an environment
  variable precisely so the file itself is safe to check in.
</Warning>

## Local development

The quickest path on a personal machine is to write the credential to your
**user-level** `~/.npmrc`, where it applies to every project and cannot be
committed by accident:

```bash theme={null}
npm config set @reviseio:registry https://registry.npmjs.org/
npm config set //registry.npmjs.org/:_authToken npm_xxxxxxxxxxxxxxxxxxxx
npm install @reviseio/sdk
```

If you would rather keep the configuration in the repository — which you will
want anyway for CI — commit a project `.npmrc` that reads the token from the
environment:

```ini .npmrc theme={null}
@reviseio:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${REVISE_NPM_TOKEN}
```

The first line routes only the `@reviseio` scope; every other dependency
resolves exactly as before. The second supplies the credential, expanded from
your environment at install time.

```bash theme={null}
export REVISE_NPM_TOKEN=npm_xxxxxxxxxxxxxxxxxxxx
npm install @reviseio/sdk
```

<Warning>
  If the variable is unset, npm sends the literal string
  `${REVISE_NPM_TOKEN}` and the error reads like an invalid token rather than a
  missing one. Confirm with `echo $REVISE_NPM_TOKEN` in the same shell.
</Warning>

### Yarn 2 and newer

Yarn Berry ignores `.npmrc`. Configure the scope in `.yarnrc.yml` instead:

```yaml .yarnrc.yml theme={null}
npmScopes:
  reviseio:
    npmRegistryServer: "https://registry.npmjs.org"
    npmAuthToken: "${REVISE_NPM_TOKEN}"
```

Yarn 1 and pnpm both read `.npmrc` and need no special handling.

## Continuous integration

Store the token as a secret and export it in the job. The committed `.npmrc`
needs no changes.

<CodeGroup>
  ```yaml GitHub Actions theme={null}
  - uses: actions/setup-node@v4
    with:
      node-version: 20
  - run: npm ci
    env:
      REVISE_NPM_TOKEN: ${{ secrets.REVISE_NPM_TOKEN }}
  ```

  ```yaml GitLab CI theme={null}
  build:
    script:
      - npm ci
    variables:
      REVISE_NPM_TOKEN: $REVISE_NPM_TOKEN
  ```

  ```dockerfile Docker theme={null}
  # Mount the secret rather than baking it into a layer.
  RUN --mount=type=secret,id=npm_token \
      REVISE_NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci
  ```
</CodeGroup>

<Warning>
  In Docker, avoid `ARG`/`ENV` for the token — it persists in the image
  history. Use a mounted build secret, as above.
</Warning>

## Behind a registry proxy

If your organisation routes installs through Artifactory, Nexus, Verdaccio, or
similar, developers cannot authenticate directly and the token belongs in the
proxy instead. Your platform team configures a remote repository for
`registry.npmjs.org` with the token as its upstream credential, scoped to
`@reviseio`. Developers then install normally, with no token and no `.npmrc`
change.

Tell us if this is your setup — it changes nothing about the package, but it is
worth confirming the scope is routed before your first install.

## Versioning

The package follows semantic versioning. Pin what you ship:

```json package.json theme={null}
{
  "dependencies": {
    "@reviseio/sdk": "0.1.0"
  }
}
```

Breaking changes to the component props or the handle controllers arrive in a
major version, never a patch.

## Rotating or revoking

Tokens can be reissued at any time — ask, and the old one stops working the
moment the new one is generated. Rotate immediately if a token appears in a
build log, a public repository, or a support ticket.

## Troubleshooting

<AccordionGroup>
  <Accordion title="404 Not Found on @reviseio/sdk">
    The scope is not routed or the token is not being read. Check that
    `.npmrc` sits at the project root, and that `echo $REVISE_NPM_TOKEN`
    prints a value in the same shell you are installing from. npm reports
    private packages you cannot see as 404 rather than 403.
  </Accordion>

  <Accordion title="401 Unauthorized">
    The token is present but rejected — usually revoked, expired, or truncated
    in transit. Ask us to reissue.
  </Accordion>

  <Accordion title="Works locally, fails in CI">
    The secret is not exposed to the install step. Confirm the environment
    variable is set on the job that runs `npm ci`, not only at the workflow
    level.
  </Accordion>

  <Accordion title="ERESOLVE peer dependency errors">
    The package needs React 18 or newer as a peer. On React 17 or earlier the
    install fails by design.
  </Accordion>

  <Accordion title="Yarn cannot find the package">
    Yarn 2 and newer ignore `.npmrc` entirely. The scope must be configured in
    `.yarnrc.yml` — see [Yarn 2 and newer](#yarn-2-and-newer) above.
  </Accordion>
</AccordionGroup>