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. (Node.js v20, v22 & v23 describe instead corepack use / corepack install.)

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.

[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

[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.

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.