Getting started

nextpm uses the npm registry protocol. npm, pnpm, Bun, and Yarn work with it, and need no plugin. On this page, registry.example.com is the registry host, and example.com is the website.

Before you start#

You need:

• npm 9 or later, pnpm, Bun, or Yarn 2 or later
• an account on example.com, with a passkey

npm 9 and later sign in through the website. You approve each sign-in with your passkey.

Create an account#

1. Open https://example.com/signup.
2. Enter a user name, your email, and a password of 10 or more characters.
3. Open Edit profile from the account menu. Under Passkeys, add a passkey.
4. Keep the 10 recovery codes in a safe place. Each code works once, in place of the passkey.

Note

Your user name is also your scope. Packages named @alice/… belong to the user alice. Users and Orgs share one set of names.

Point your client at nextpm#

Each client reads the registry host from a config file. Put the file in a project to use nextpm for that project. Put it in your home folder to use nextpm for all projects.

npm and pnpm#

npm and pnpm read .npmrc:

registry=https://registry.example.com/

You can also set it from the command line:

npm config set registry https://registry.example.com/

Bun#

Bun also reads .npmrc. To keep the setting in bunfig.toml instead:

[install]
registry = "https://registry.example.com/"

Yarn#

Yarn 2 and later read .yarnrc.yml:

npmRegistryServer: "https://registry.example.com"
npmAuthToken: "${NPM_TOKEN}"

Yarn does not use the website sign-in. Make a token in Settings, under Tokens, and put it in the NPM_TOKEN environment variable. This token can only install. Yarn cannot publish to nextpm yet: it asks for a one-time code, and nextpm approves each change with a passkey.

Sign in#

1. Run npm login:

   ShellCopy

   npm login --registry https://registry.example.com/

2. npm opens the sign-in page of example.com. Sign in with your passkey or your password.

3. Select Authorize npm CLI, and confirm with your passkey.

4. npm gets a token named npm login, and writes it to your .npmrc. The token lives 30 days. Each publish or other change with it waits for your passkey.

Make sure that it worked:

npm whoami --registry https://registry.example.com/

pnpm and Bun use the same token, because they read the same line of .npmrc:

//registry.example.com/:_authToken=nextpm_…

Important

An account with no passkey cannot approve npm login. Add a passkey first.

Tip

If you have no account yet, run npm adduser instead. It opens the sign-up page.

Publish a package#

1. Make a folder with a package.json. Put your scope in the name:

   ShellCopy

   mkdir hello && cd hello
   npm init --scope=@alice -y

2. Publish it:

   ShellCopy

   npm publish --access public

   With pnpm, run pnpm publish --access public. With Bun, run bun publish --access public.

3. npm prints the address of an approval page, and waits. Open it, check the change, and select Approve with passkey. npm then finishes the publish. See Publish from a terminal.

4. Open https://example.com/package/@alice/hello to see the release, its seal, and its files.

The name of a package sets who can publish it:

After the first version, the maintainers of the package can also publish it.

Warning

You cannot use a version number again, also after you unpublish it.

Install a package#

Each client installs from the registry in its config:

npm install @alice/hello
pnpm add @alice/hello
bun add @alice/hello
yarn add @alice/hello

A restricted package needs a token that can read it. Until the backfill brings npm's packages here, the registry gets the names that it never held from registry.npmjs.org, so one host serves all your dependencies.

Next steps#

• Publish from GitHub Actions with no stored token: Publishing.
• Keep a scope off the public registry: Private registries.
• Learn what the picture on each release means: Release seals.