Skip to content

Support peerDependenciesMeta.optional during dependency resolution #3232

Description

@elrrrrrrr

Problem

Utoo currently does not fully honor npm's peerDependenciesMeta.<name>.optional semantics during dependency resolution. Optional peer dependencies may still be treated like required peers / included in the install graph, which can install unnecessary large packages.

This is especially costly for packages such as ORMs that support multiple optional database clients (for example mysql, mysql2, pg, sqlite3, and sql.js). Applications normally use only one client.

Minimal reproduction

Dependency package:

{
  "peerDependencies": {
    "sqlite3": "^5.0.2"
  },
  "peerDependenciesMeta": {
    "sqlite3": {
      "optional": true
    }
  }
}

Consumer:

{
  "dependencies": {
    "the-package": "latest"
  }
}

Run:

utoo install

Expected behavior

  • Missing optional peers do not produce missing-peer resolution errors or warnings.
  • Optional peers are not automatically installed solely because they appear in peerDependencies.
  • If the consumer explicitly installs the peer, its version is validated against the declared range.
  • Lockfile and dependency-tree behavior matches npm/pnpm/Bun semantics.

Environment

  • Utoo: 1.0.32
  • Node.js: 24.14.0
  • macOS arm64

Real-world case

leoric@2.14.0 declares its database clients as optional peers. Correct handling avoids downloading native SQLite packages and unused database drivers for applications that only use MySQL.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions