Skip to Content

Package access

The Modem SDK packages use the @preternatural-js scope on GitHub Packages, not anonymous public npm access. Configure this once in the application that will install them. A Modem admin API key or CLI login does not authenticate a package manager to GitHub.

Get read access

Your GitHub account needs read access to the packages, including their private dependencies. Ask the package owner to grant access if necessary. A repository invitation alone may not grant package access when its permissions are configured separately. See GitHub package permissions .

For local installation, use a personal access token (classic) with read:packages and the required account access. Publishing/deletion scopes are not needed to install. Follow your organization’s token and SSO authorization requirements. GitHub documents the supported token type in its npm registry guide .

Configure the registry

Create or merge this .npmrc beside your application’s root package.json:

@preternatural-js:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

Keep the ${GITHUB_TOKEN} reference literal in this file; never replace it with a real token in a committed file. The scope mapping leaves unrelated packages on their normal registry. The same configuration covers private @preternatural-js dependencies such as api-schema.

Supply GITHUB_TOKEN to the package-manager process through your secret manager or an untracked local environment file. For Bun, a local .env.local can contain:

GITHUB_TOKEN=YOUR_GITHUB_PACKAGES_READ_TOKEN

Replace that placeholder locally and ensure .env.local is ignored by Git. Bun supports the .npmrc scope/token syntax and environment substitution; see Bun’s configuration precedence . An overriding bunfig.toml, registry flag or registry environment setting can change which configuration is used.

Install only the packages your application needs:

bun add @preternatural-js/client-sdk

For administration, install @preternatural-js/admin-sdk instead. For an application-owned chat server, install @preternatural-js/self-hosted-app-server-sdk. See version availability before selecting a specific version. npm users can use npm install with the same .npmrc, but must supply the environment variable to npm themselves; npm does not load Bun’s dotenv files.

CI installation

Keep the scope mapping and variable reference in the project; put the token in the CI secret store. In GitHub Actions, the workflow’s GITHUB_TOKEN needs packages: read, and the workflow repository must have access to every private package it installs. A permission declaration alone does not grant another repository’s package access. Package owners configure that under Manage Actions access .

Pass the Actions token explicitly to the install step. For example, in a job that already checks out the project and installs Bun:

permissions: contents: read packages: read steps: # Checkout and Bun setup steps go before this step. - name: Install dependencies run: bun install --frozen-lockfile env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This uses the existing lockfile and the project’s .npmrc. See GitHub Actions token authentication .

For other CI systems, provide a permitted classic token as GITHUB_TOKEN. Do not print it, expand it into logged commands or store it in build output.

Installation failures

ResultCheck
401 or authentication errorThe variable is present, the token has not expired, and the credential is configured for npm.pkg.github.com.
403 or permission errorToken scope, account/package access, workflow repository access and any required organization authorization.
404 or package/version not foundScope mapping, exact package/version and read access; a hidden private package can look missing.
A private dependency failsRead access must cover dependencies too, not only the package named in bun add.

Do not post your .npmrc with resolved secrets or raw authenticated registry responses when reporting an install failure. Include the package/version, registry hostname and redacted error instead.

Last updated on