Switch to devEngines.packageManager in "When Authoring Packages"

[karlhorky]

Hi, thanks for Corepack! It's been a useful tool to maintain environments across student machines.

In the When Authoring Packages section of the readme, the instructions start with suggesting using a top-level packageManager field of package.json:

Set your package's manager with the packageManager field in package.json:

{
  "packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa"
}

Further down in the readme, there is a subsection devEngines.packageManager, which shifts to describing the devEngines.packageManager field:

devEngines.packageManager

When a devEngines.packageManager field is defined, and is an object containing
a "name" field (can also optionally contain version and onFail fields),
Corepack will use it to validate you're using a compatible package manager.

devEngines.packageManager has some level of support in:

1. npm v10+ https://docs.npmjs.com/cli/v10/configuring-npm/package-json#devengines
2. Yarn via Corepack
3. pnpm https://pnpm.io/package_json#devenginespackagemanager

My suggestion is regarding that first starting section of the readme on the top-level packageManager field:

1. replace the packageManager docs with devEngines.packageManager docs (without the extra subsection)
2. and then either:
   1. drop the packageManager docs
   2. deprioritize the packageManager docs by moving them to the end and describing it as "Legacy" or similar

[arcanis]

No, the packageManager field is the recommended universal field, devEngines is a separate one that isn't supported by all tooling.

Yarn via Corepack

Yarn doesn't support the packageManager and has no plan to do it (yarn set version sets the packageManager field and has no special support for whether devEngines is set).

[karlhorky]

No, the packageManager field is the recommended universal field

Ok interesting, can you provide some references from this? Or do you only mean in terms of Corepack, not the wider package manager / interop community?

From my research it seems like the top-level packageManager field was considered legacy / insufficient:

1. npm package.json docs do not mention packageManager at all (probably since npm won't support it)

2. pnpm package.json docs mention "legacy" and hints at moving projects off of it:

   When pnpm is declared via the legacy packageManager field (not devEngines.packageManager), its resolution info is not written to pnpm-lock.yaml — unless the pinned pnpm version is v12 or newer. This keeps the lockfile stable when upgrading from pnpm v10 to v11 without forcing projects off the legacy field.

3. @GeoffreyBooth wrote about packageManager limitations in packageManager field is too limited #402:

   The packageManager field as currently designed is too limited for what I want to do

   @benmccann wrote about lack of ranges in package-manager-strict enforcement in pnpm 9 is a massive headache pnpm/pnpm#8087:

   Support for semver ranges is the number two issue in corepack

[arcanis]

Ok interesting, can you provide some references from this? Or do you only mean in terms of Corepack, not the wider package manager / interop community?

I wrote Corepack and implemented support for packageManager. It's widely used in the ecosystem by Corepack and other tools. I think if you search on GH you'll find significantly more hits than for devEngines.

The devEngines was designed by the "package maintenance group" whose members notably don't include package manager authors outside of active and former npm collaborators. I'm sure they have the best intentions, but I find their approach of package management differing a bit from what I feel comfortable with.

Support for semver ranges is the number two issue in corepack

More opportunities for unlocked versions and supply chain attacks didn't seem a great idea to me then and it doesn't seem a great idea now. The packageManager field not supporting ranges is a feature, not a bug.