npm, pnpm, Yarn and Bun

This page sets up a project to install packages from Telesphorepo. To publish a package, see Publish from a project, under Publish your packages; what is different for npm is under Publish to this repository.

An admin first makes a repository with the format npm (see Make a repository). The examples use the server repo.example.com and a repository named js, so the registry is this:

https://repo.example.com/npm/js/

Put your own values in the blocks below. The Use this repository tab of the repository shows the same blocks with your values.

Install packages

1. Point the project at the repository. Put the file in the project folder, next to package.json.

   .npmrc, anyone can download

   .npmrc

   registry=https://repo.example.com/npm/js/

   .npmrc, only signed-in people

   .npmrc

   registry=https://repo.example.com/npm/js/
   //repo.example.com/npm/js/:_authToken=${NPM_TOKEN}

   The second line names the registry without https:. The file holds no token, so you can commit it.

   .yarnrc.yml, your own packages, anyone can download

   .yarnrc.yml

   npmRegistryServer: "https://repo.example.com/npm/js/"
   npmMinimalAgeGate: 0

   .yarnrc.yml, your own packages, only signed-in people

   .yarnrc.yml

   npmRegistryServer: "https://repo.example.com/npm/js/"
   npmAlwaysAuth: true
   npmAuthToken: "${NPM_TOKEN}"
   npmMinimalAgeGate: 0

   .yarnrc.yml, public packages too, anyone can download

   .yarnrc.yml

   npmRegistryServer: "https://repo.example.com/npm/js/"

   .yarnrc.yml, public packages too, only signed-in people

   .yarnrc.yml

   npmRegistryServer: "https://repo.example.com/npm/js/"
   npmAlwaysAuth: true
   npmAuthToken: "${NPM_TOKEN}"

   Yarn and the age gate, your own packages

   Yarn 4 installs a version only once it is a week old. npmMinimalAgeGate: 0 turns that off, so Yarn installs a version that you published a minute ago.

   Yarn and the age gate, public packages too

   Yarn 4 installs a version only once it is a week old. To install your own packages at once, list them in npmPreapprovedPackages, for example - "@acme/*".

2. Make a read token, and give it to the package manager.

   Anyone can download

   Skip this step. Anyone can download.

   Only signed-in people

   Settings › Tokens › New read token. Type a name, then click Create token. Then paste the token at the hidden prompt:

   printf 'Read token: '; read -rs NPM_TOKEN; echo
   export NPM_TOKEN

   In CI, keep the token in a secret, and set NPM_TOKEN to it.

3. Install a package.

   npm

   npm install @acme/ui@1.2.0

   pnpm

   pnpm add @acme/ui@1.2.0

   Yarn

   yarn add @acme/ui@1.2.0

   Bun

   bun add @acme/ui@1.2.0

Done when the install ends with no error, and node_modules holds the package.

Your own packages

A hosted repository holds your own packages only. The package manager then cannot find a public package such as react through it. To install both through one address, ask your server admin for a group of your repository and a proxy of registry.npmjs.org. Then point the project at the group.

Public packages too

A group asks its members in order. The first member that has a package name owns it, and the group serves every version of that name from that member only. So a public package with the name of your private package cannot take its place, even with a higher version. Your admin puts your hosted repository before the proxy.

Publish to this repository

Publish as in Publish from a project: run the setup line in the folder that holds package.json, commit telesphorepo.toml, then run telesphorepo publish. Done when the publish ends with no error, and the version shows on the repository page in the web UI.

The CLI picks the package manager by the lockfile, and runs its publish with a publish token for this one repository:

Lockfile	The CLI runs
pnpm-lock.yaml	pnpm publish --no-git-checks
yarn.lock and .yarnrc.yml	yarn npm publish
bun.lock or bun.lockb	bun publish
none of these	npm publish

The package manager packs the package, so files, prepack and workspace: ranges work as usual. You do not run npm login. You do not change package.json or .npmrc to publish.

The CI file for npm

Publish from CI has the steps. When you choose GitHub Actions at setup, the CLI writes this file for the package manager of the project:

GitHub Actions with npm

.github/workflows/publish.yml

on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v5
        with:
          node-version: lts/*
      - run: npm ci
      - run: curl -fsSL https://repo.example.com/install.sh | sh
      - run: telesphorepo publish

GitHub Actions with pnpm

.github/workflows/publish.yml

on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v5
        with:
          node-version: lts/*
      - run: pnpm install --frozen-lockfile
      - run: curl -fsSL https://repo.example.com/install.sh | sh
      - run: telesphorepo publish

GitHub Actions with Yarn

.github/workflows/publish.yml

on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v5
        with:
          node-version: lts/*
      - run: corepack enable && yarn install --immutable
      - run: curl -fsSL https://repo.example.com/install.sh | sh
      - run: telesphorepo publish

GitHub Actions with Bun

.github/workflows/publish.yml

on:
  push:
    branches: ["main"]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: curl -fsSL https://repo.example.com/install.sh | sh
      - run: telesphorepo publish

The identity token publishes only. If the install step reads a private repository, keep a read token in a CI secret and set NPM_TOKEN to it in that step. For Jenkins, see Publish from CI.

If something goes wrong

Yarn does not install a version that you just published

Yarn 4 installs a version only once it is a week old. For a hosted repository, add npmMinimalAgeGate: 0 to .yarnrc.yml. For a group or a proxy, list your own packages in npmPreapprovedPackages.

401 when Yarn installs from a private repository

Yarn sends the token on installs only with npmAlwaysAuth: true. Add it to .yarnrc.yml.

401 when npm, pnpm or Bun installs

Check that NPM_TOKEN holds a read token, and that the _authToken line names the same address as registry=, without https:.

Yarn refuses an http:// server

Add the host name of the server to unsafeHttpWhitelist in .yarnrc.yml. For real use, serve the server over HTTPS. See Serve over HTTPS.

The package manager cannot find a public package

The repository is hosted, and holds your own packages only. Ask your server admin for a group with a proxy of registry.npmjs.org.

A group serves your private package, not the public one with the same name

The first member that has a name owns it. Rename your package, or ask your admin to change the order of the members.

npm login is not used with Telesphorepo

To install, put a read token in .npmrc. To publish, run telesphorepo publish.

403 version 1.2.0 of x already exists

That version is on the server. Raise the version in package.json.

The CLI says that the project publishes with pnpm, and pnpm is not on the PATH

The CLI picks the package manager by the lockfile. Install that package manager, or remove the lockfile of the one you do not use.

You want to take a version back

Open the repository in the web UI, then the Files tab, and delete the tarball of the version. The server then drops that version from the package. You need Delete on the repository. A CI job cannot unpublish.