feat: let .corepack.env be a lock file

[aduh95]

With #642 and #643 landed, we can consider using .corepack.env as a lockfile. If the package.json defines a devEngines.packageManager, we can accept an env variable that defines the exact version Corepack should be using; if that version is put in a .corepack.env (Node.js 20+ users only), it's effectively a lockfile.

I'm not a fan of the env variable name chosen, happy to use a different one.

Fixes: #402
Fixes: #95
Fixes: #682

[styfle]

To be clear, this is only going to update .corepack.env if it already exists.

Its not going to create .corepack.env if it does not exist, right?

[aduh95]

To be clear, this is only going to update .corepack.env if it already exists.

Its not going to create .corepack.env if it does not exist, right?

Yes correct, if it exists and contains the env key – so it’s currently opt-in, I think we could discuss whether we want to flip that to opt-out once the parseEnv thing is no longer experimental.

[arcanis]

Why do we need that considering that packageManager can already be used as a lock for devEngines.packageManager?

[aduh95]

Why do we need that considering that packageManager can already be used as a lock for devEngines.packageManager?

So one can git ignore it I believe is the ask

[arcanis]

I'm not sure I follow the use case. Why would they use Corepack (or devEngine) if they don't want to lock the version in the project?

[zanminkian]

@arcanis I have the same use-case as @aduh95. When developing some old projects, they usually reject to add packageManager and devEngines field to package.json. Corepack is convenient for me but not every team member like it. I can use corepack with a git ignored .corepack.env file on my own way.

[arcanis]

Then disable auto pinning? I don't think this behavior should have been made the default anyway.

[aduh95]

@zanminkian could you give an example of use case where putting a .gitignored .corepack.env with COREPACK_ENABLE_AUTO_PIN=0 would not fulfill your needs?

[styfle]

Then disable auto pinning? I don't think this behavior should have been made the default anyway.

I tend to agree. I believe the default auto-pinning was added as a response to earlier TSC meetings where this was a recommendation to making corepack stable and default enabled with node distributions.

Now that corepack is no longer going to be bundled with node, we could consider disabling the auto pinning behavior.

[khokm]

Linked issues: #465
I support moving the packageManager field out of package.json into a separate file. This can be especially useful for Docker workflows like:

RUN corepack enable

# Copy package.json so corepack can read the packageManager field
COPY package.json ./package.json
RUN corepack prepare

COPY pnpm-lock.yaml pnpm-workspace.yaml ./
# pnpm fetch is a time-consuming operation
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm fetch

Currently, any change in package.json that does not affect the build—for example, adding a new entry in scripts—forces Docker to invalidate the cache.

An alternative would be using corepack install -g pnpm@, but that requires keeping the packageManager field in package.json and the pnpm version in the Dockerfile in sync.

Having a separate file (like a proposed .corepack.env) containing only packageManager version would theoretically change much less frequently than package.json, reducing unnecessary Docker cache invalidation.

My current workaround is instead of copying package.json, to read only packageManager from it and pass it as an ARG