JavaScript/TypeScript

Support for Node.js projects using package.json.

Table of contents

  1. Supported Files
    1. Lockfile Resolution
  2. Registry
    1. Private Registries
  3. Dependency Formats
    1. Dependencies
    2. Dev Dependencies
    3. Peer Dependencies
    4. Optional Dependencies
    5. pnpm Workspace Catalogs
  4. Version Specification
  5. Special Cases
    1. Scoped Packages
    2. Git Dependencies
    3. Local Dependencies
    4. npm Aliases
    5. Deprecated Packages
  6. Dist Tags
  7. Vulnerability Database
  8. Example package.json
  9. Troubleshooting
    1. Scoped Package Not Found
    2. Stale Versions
    3. Rate Limiting

Supported Files

File Description
package.json npm/yarn/pnpm manifest
pnpm-workspace.yaml pnpm workspace catalogs (catalog and catalogs)

Lockfile Resolution

Depsy reads lockfiles to show resolved versions and eliminate false-positive “update available” warnings:

Lockfile Tool
package-lock.json npm (lockfileVersion 1, 2, 3)
yarn.lock Yarn Classic v1 and Berry v2+
pnpm-lock.yaml pnpm v6 and v9
bun.lock Bun (text JSONC format)

Registry

npm - The Node.js package registry

  • Base URL: https://registry.npmjs.org
  • Rate limit: ~1 request per second recommended
  • Documentation: npmjs.com

Private Registries

npm supports custom registries. See Private Registries for setup.

Dependency Formats

Depsy parses all npm dependency sections:

Dependencies 

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "4.17.21"
  }
}

Dev Dependencies 

{
  "devDependencies": {
    "typescript": "^5.0.0",
    "jest": "^29.0.0"
  }
}

Peer Dependencies 

{
  "peerDependencies": {
    "react": "^18.0.0"
  }
}

Optional Dependencies 

{
  "optionalDependencies": {
    "fsevents": "^2.3.0"
  }
}

pnpm Workspace Catalogs 

packages:
  - packages/*
catalog:
  react: ^18.3.1
catalogs:
  legacy:
    react: ^17.0.2

Opening pnpm-workspace.yaml gives every entry of the default catalog and of each named catalog under catalogs the same inlay hints, diagnostics, vulnerability checks and update code actions as a package.json dependency. Other keys of the file (packages, overrides, …) are ignored.

In package.json, catalog: and catalog:<name> references resolve to the version pinned in the nearest pnpm-workspace.yaml.

Catalog entries are resolved against the catalogs section of the pnpm-lock.yaml next to the workspace file, so each entry gets the version locked for its own catalog; lockfiles of other package managers are ignored. Entries that no workspace project references are absent from that section, and entries whose range changed since the last pnpm install no longer match the locked specifier; both are checked against their declared range instead.

Version Specification

npm uses semantic versioning:

Syntax Meaning
"1.0.0" Exactly 1.0.0
"^1.0.0" >=1.0.0, <2.0.0
"~1.0.0" >=1.0.0, <1.1.0
"*" Any version
">=1.0.0" 1.0.0 or higher
"1.0.0 - 2.0.0" Range
"latest" Latest tag

Special Cases

Scoped Packages 

{
  "dependencies": {
    "@types/node": "^20.0.0",
    "@company/internal": "^1.0.0"
  }
}

Scoped packages (@scope/name) are fully supported. For private scopes, configure Private Registries.

Git Dependencies 

{
  "dependencies": {
    "my-lib": "git+https://github.com/user/repo.git"
  }
}

Git dependencies show → Git hint.

Local Dependencies 

{
  "dependencies": {
    "my-local": "file:../my-local"
  }
}

Local dependencies show → Local hint.

npm Aliases 

{
  "dependencies": {
    "lodash-es": "npm:lodash@^4.17.0"
  }
}

Aliases are resolved to the actual package.

Deprecated Packages

Deprecated packages show ⚠ Deprecated hint with the deprecation message on hover.

Dist Tags

npm packages can have distribution tags:

  • latest - Default stable version
  • next - Pre-release version
  • beta, alpha - Testing versions

Depsy checks against latest by default.

Vulnerability Database

npm vulnerabilities are sourced via the OSV.dev API, which aggregates:

Example package.json 

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0",         // ✓
    "lodash": "4.17.15",          // -> 4.17.21
    "@types/node": "^20.0.0"      // ✓
  },
  "devDependencies": {
    "typescript": "^5.0.0",       // -> 5.3.0
    "jest": "^29.0.0"             // ✓
  }
}

Troubleshooting

Scoped Package Not Found

For private scoped packages:

  1. Configure the scope in Private Registries
  2. Ensure authentication token is set
  3. Verify the scope name doesn’t include @ in config

Stale Versions

npm has heavy CDN caching. If a just-published version isn’t showing:

  1. Wait a few minutes for CDN propagation
  2. Clear Depsy cache and restart Zed

Rate Limiting

npm may block aggressive requests. Depsy’s caching minimizes API calls, but large monorepos may experience slower initial loads.