Handling of deprecated / hidden commands `hydrate` & `prepare`

[MikeMcC399]

Issue

• The following commands are hidden since PR Refactoring of the CLI interface #291 implemented RFC: New command names (and alias the old ones) #274 in release corepack@0.20.0:

  • corepack hydrate
  • corepack prepare

These commands:

1. are not documented in the README
2. have no migration guide to their replacement commands
3. do not appear in the output of corepack --help
4. are described in the output of corepack hydrate --help and corepack prepare --help
5. neither their usage, nor their help text indicates that the commands are deprecated

Several issues lately have shown users reporting problems when executing corepack prepare.

corepack prepare is listed as a valid command in Node.js documentation Corepack latest v18 Edit: Node.js 18 is now in end-of-life status, so documentation should no longer be referred to. (Node.js v20, v22 & v23 describes instead corepack use / corepack install. Edit: v22 and v24 documentation now have no detailed content.)

Suggestion

1. Describe the above commands as deprecated and either add the a migration table from RFC: New command names (and alias the old ones) #274 to the README or create a separate Migration Guide document. Edit: the migration table in the PR contains inaccuracies and cannot be used as it stands.
2. Extend the help text for the commands to indicate that they are deprecated.
3. Output a deprecation warning if deprecated commands are used.

Also review Node.js documentation Corepack latest v18 and initiate an update if possible. Edit: Node.js 18 has passed into end-of-life status, so all related assets are now frozen.

Related Node.js documentation

• Node.js 18 Corepack (Node.js 18 is end-of-life)
• Node.js 20 Corepack
• Node.js 22 Corepack
• Node.js 24 Corepack
• Node.js latest Corepack

[MikeMcC399]

I would like to submit a PR to add a migration table to the README. As a first pass to creating the table it would look like this:

Deprecated command	Replacement command
corepack hydrate path/to/archive.tgz	corepack install -g --cache-only path/to/archive.tgz
corepack hydrate path/to/archive.tgz --activate	corepack install -g path/to/archive.tgz
corepack prepare foo@1.2.3	corepack install -g --cache-only foo@1.2.3
corepack prepare foo@1.2.3 --activate	corepack install -g foo@1.2.3
corepack prepare -o ...	corepack pack -o ...

Is this something that maintainers would welcome to have added to the README?

For consistency, --cache-only should probably also be added to the corepack install <-g,--global> [... name[@]] section as an option as well.

[MikeMcC399]

I'm waiting for an acknowledgement that a PR as described above would be considered before I submit one.

[MikeMcC399]

• PR submitted docs: add deprecated commands to README #685

Edit: I closed this PR after there was no response

[MikeMcC399]

The documentation for Corepack in Node.js 18, as mentioned in the OP, is outdated.

https://nodejs.org/docs/latest-v18.x/api/corepack.html for Node.js v18.20.8 lists deprecated commands prepare and hydrate

https://github.com/nodejs/node/tree/v18.20.8 contains Corepack 0.32.0 together with the documentation for Corepack prior to corepack@0.20.0 where these commands were deprecated. So documentation and bundled Corepack are mismatched.

If there is going to be a final release of Node.js 18.x before it enters EOL on Apr 30, 2025, perhaps the documentation page could be corrected for posterity?

cc: @trivikr

[trivikr]

If there is going to be a final release of Node.js 18.x before it enters EOL on Apr 30, 2025

There is not new release Node.js 18.x planned AFAIK.
This is based on a skeet from active releaser when v18.20.8 was released.

The future versions of 20.x and 22.x will get the decision in bold and call to action added in nodejs/node#57825

[MikeMcC399]

@trivikr

Thanks for the research! According to the table in nodejs/Release#737, I also would not expect any 18.x release after v18.20.8. Edit: Node.js 18 is now end-of-life and the last Node.js 18 release was indeed v18.20.8

I will be watching for the future Node.js releases, although by now I have removed any links I originally had in any documentation / code that point to Corepack on the Node.js site, so my content shouldn't be impacted anymore anyway.