Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Packages and package.json

The npm Registry and Package Names

Learn how the npm registry stores packages, how scoped names like @scope/name work, what a package document and tarball contain, and how to use other or private registries with .npmrc.

The registry is the other half of every npm install. It is an HTTP service that answers two questions: "what versions of this package exist?" and "give me the files for this version". Knowing how it is organized helps you pick trustworthy packages, understand scoped names and point your tools at a private registry.

What the registry stores

For each package name the registry keeps a packument, one JSON document listing every published version, the dist-tags (such as latest) and per-version metadata. Each version points to a tarball: a .tgz archive of the files, with a checksum so downloads can be verified.

Public registry endpoints are plain HTTPS. On your own computer you can look at any package with:

Terminal
npm view express                    # summary
npm view express versions --json    # every version
npm view express dist-tags          # latest, next, ...
npm view express dist.tarball       # download URL

An install therefore does this: ask the registry for the packument, pick a version that satisfies your range, then download that version's tarball and unpack it.

A packument, modelled

This stand-in uses a miniature packument to show how a manager picks a version for latest and how the tarball URL is built.

Node.js Read a (fake) packument

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

latest is only a label: it is what plain npm install name resolves to. Publishers may also publish under other tags (next, beta) so that testers can opt in with npm install name@next without affecting everyone else. Tags are covered in the Publishing chapter.

Package names

Names are unique on the registry, first come, first served. Rules: URL-safe, lowercase, no leading dots or underscores, and at most 214 characters. Dots, dashes and underscores are fine.

A scope groups packages under an owner. Scoped names look like @scope/name:

  • @types/node (type definitions), @babel/core, @acme/date-tools.
  • Scopes belong to a user or organization, so nobody else can publish under @acme/.
  • Scoped packages are published private by default; to make a public one use npm publish --access public.
Node.js Parse and validate package names

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Beware of typosquatting: attackers publish names like expres or lodahs hoping you mistype. Always double-check the spelling and the download count before installing something new. See the Security chapter for more.

Choosing other registries

Companies often run a private registry (Verdaccio, GitHub Packages, Artifactory, a cloud vendor's registry) for internal code. You point your manager to it in an .npmrc file:

INI
# .npmrc in your project (committed, no secrets)
registry=https://registry.npmjs.org/
@acme:registry=https://npm.pkg.example.com/

The second line routes only @acme/* packages to the private registry while everything else uses the public one. Credentials go in your user-level ~/.npmrc or an environment variable, never in a file committed to git:

INI
//npm.pkg.example.com/:_authToken=${NPM_TOKEN}

pnpm reads .npmrc as well. Yarn Berry uses .yarnrc.yml with equivalent keys (npmRegistryServer, npmScopes).

Resolving a scoped registry in code

Node.js Which registry serves this package?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Reading a package's page

Before depending on a package, check: when it was last published, how many maintainers it has, whether it has a repository link and license, its weekly downloads, open issues and how many dependencies it brings. Small, maintained packages with clear licenses are safer than abandoned giants. A comparison habit worth having: npm view <name> time.modified license dependencies.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a registry packument list?

    The packument is the full metadata document for a package.
  2. 2. Who can publish packages under the @acme scope?

    Scopes are owned, which prevents name clashes and impersonation.
  3. 3. Where should registry auth tokens be stored?

    Never commit secrets; use user-level config or env variables.
  4. 4. What is typosquatting?

    Attackers rely on typing mistakes; verify names before installing.

Summary

  • The registry serves a packument (all versions and tags) and a tarball per version.
  • latest is just a dist-tag; other tags enable opt-in channels.
  • Names are lowercase and unique; @scope/name groups packages under an owner.
  • .npmrc (or .yarnrc.yml) points tools at other registries; keep tokens out of git.
  • Check maintenance, license and dependencies before adopting a package.

Next: Installing Packages