package-json

package-json is a small Node.js library that queries the npm registry (or any registry conforming to its API) for a package’s metadata — name, versions, dependencies, dist tags, and more — and returns it as a plain JavaScript object. It works with scoped packages out of the box, resolves the correct registry URL and authentication from the caller’s existing .npmrc, and lets you ask for the latest version, a specific version, or anything matched via a semver range or dist tag.

By default it returns the compact ‘abbreviated’ metadata format for speed, with an option to fetch the full CouchDB-style document when more detail (like publish history or full package.json fields) is needed. Deprecated versions are filtered out unless explicitly requested, and lookup failures surface as typed PackageNotFoundError / VersionNotFoundError classes rather than generic errors.

What You Get

• A single packageJson(name, options) function that returns npm registry metadata for any public or private package
• Automatic support for scoped packages (e.g. @sindresorhus/df) with no special-casing required by the caller
• Version resolution against exact versions, dist tags (latest, etc.), or semver ranges (^1.2.3, ~1.2.3, 1.2, 1)
• Automatic filtering of deprecated versions, with an omitDeprecated flag to opt out
• Transparent private-registry authentication (bearer or basic) resolved from the caller’s existing .npmrc
• Typed PackageNotFoundError and VersionNotFoundError classes for precise error handling
• Full TypeScript types for both the abbreviated and full metadata response shapes

Common Use Cases

• Checking whether a newer version of a dependency is published before recommending an upgrade
• Building CLI tools that need to resolve a package name/version pair against the registry (e.g. npx-style tools)
• Fetching a package’s declared dependencies/engines/bin fields without cloning or installing it
• Validating that a package name exists and isn’t deprecated before scaffolding a project around it
• Querying private/internal registries with the same code path used for the public npm registry

Under The Hood

Architecture The package is effectively one file: a default export packageJson() plus two named error classes, PackageNotFoundError and VersionNotFoundError. The function derives the package’s scope, resolves the correct registry endpoint via the companion registry-url package, resolves auth headers (bearer or basic) via registry-auth-token, issues a single GET request through ky, and then performs version resolution client-side — matching against dist-tags, an exact version, or a semver range via the semver package, filtering deprecated entries out of the version map unless omitDeprecated is disabled. There’s no internal module layering because the whole public surface is one function, but responsibility is still cleanly delegated outward: URL and auth resolution to companion sindresorhus packages, transport to ky, and range matching to semver — the core file itself is essentially a thin orchestrator over well-scoped dependencies.

Tech Stack ESM-only ("type": "module"), targeting Node.js >=18. Runtime dependencies are ky (a fetch-based HTTP client) for the network call, registry-url and registry-auth-token for resolving the correct registry endpoint and credentials from the environment’s .npmrc, and semver for version-range matching. Dev tooling is xo (an opinionated ESLint preset) for linting, ava as the test runner, tsd for asserting the shipped .d.ts types against real usage, and private-registry-mock to simulate a private registry in tests without live network calls. There’s no bundler or build step — the package ships its hand-written index.js and index.d.ts directly. CI runs the full lint/test/type-check suite across a Node 18/20/21 matrix via GitHub Actions.

Code Quality Tests in test.js exercise real calls against the live npm registry (latest version, full metadata, all versions, exact and partial semver version resolution, a custom registry URL) alongside a private-registry-mock-backed test for private-registry auth headers — genuine integration coverage rather than mocked unit tests alone. Type correctness is checked separately via tsd against index.test-d.ts, and xo enforces a strict lint/style baseline. Error handling is explicit and typed: a 404 from the registry is caught and re-thrown as a named PackageNotFoundError, an unresolvable version becomes a VersionNotFoundError, and all other fetch errors propagate unmodified rather than being swallowed. CI runs the same suite across three Node major versions on every push and pull request.

API Design The public surface is a single default export: one await packageJson(name, options) call covers the common case with sensible defaults (latest version, deprecated versions omitted), while boolean option flags (fullMetadata, allVersions) unlock progressively more detail without changing the call shape. TypeScript overloads narrow the return type based on which flags are set, so callers get an accurately typed AbbreviatedVersion, FullVersion, or metadata object without manual casting. Registry URL and auth resolution happen transparently from the caller’s existing .npmrc, so scoped and private packages need no extra configuration in the common case. The two typed error classes let callers branch on “package doesn’t exist” versus “version doesn’t exist” instead of parsing error messages.