From b48b9306ef6705c160e63c69ab3eec2ab0476634 Mon Sep 17 00:00:00 2001 From: Zoltan Kochan Date: Mon, 26 Aug 2024 02:56:59 +0200 Subject: [PATCH 1/5] Execution Environment --- text/0003-execution-env.md | 100 +++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 text/0003-execution-env.md diff --git a/text/0003-execution-env.md b/text/0003-execution-env.md new file mode 100644 index 0000000..9201961 --- /dev/null +++ b/text/0003-execution-env.md @@ -0,0 +1,100 @@ +# Execution Environments + +## Summary + +This RFC introduces settings for controlling what execution environment (Node.js, Bun, Deno) will be used for a package during: + +* runnings its lifecycle scripts +* building +* running it as a CLI app + +## Motivation + +Running multiple versions of Node.js on the same computer isn't easy. Also, there is currently no way for a package to tell the package manager that it needs to be executed with a specific version of Node.js. Node.js versions should be locked the same way as other dependencies of projects are locked for reproducibility. + +## Detailed Explanation + +We will support a new field in `package.json`: `pnpm.executionEnv.js`. This field will be similar to the `packageManager` field introduced by Corepack but will feature `@` instead. For example: + +```json +{ + "pnpm": { + "executionEnv": { + "js": "node@20.16.0" + } + } +} +``` + +or + +```json +{ + "pnpm": { + "executionEnv": { + "js": "bun@1.1.26" + } + } +} +``` + +or + +```json +{ + "pnpm": { + "executionEnv": { + "js": "deno@1.46.1" + } + } +} +``` + +When pnpm sees this setting, it will load the specified runtime and use it for: + +* running scripts locally (via the `pnpm run` and `pnpm exec` command) +* running build scripts, when installed as a dependency. If the package has a postinstall script, it will be executed by the specified runtime. +* running the package, when it is executed as a CLI. + +If we don't want to control the execution env of the published package, set the optional `localOnly` setting to `true`. For instance: + +```json +{ + "name": "cowsay", + "version": "1.0.0", + "bin": "bin.js", + "pnpm": { + "executionEnv": { + "js": "node@20.16.0", + "localOnly": true + } + } +} +``` + +In this case, pnpm will remove the `executionEnv` setting from the `package.json` file on publish and the binary of the package will be executed with whatever runtime will be installed globally on the target machine. + +## Rationale and Alternatives + +The alternative would be to use a third party tool for this (like Volta) but then we would have one more prerequisite for using pnpm. + +## Implementation + +The implementation can leverage the logic that is already present in pnpm for the `pnpm env` command, the `pnpm.executionEnv.nodeVersion` setting, the `use-node-version` setting. + +Binding CLI apps to specific Node.js versions can be done via command shims. This currently works for globally installed packages. pnpm links globally installed packages to the active Node.js version. + +## Prior Art + +We already have some functionality for managing Node.js versions: + +* the [pnpm env](https://pnpm.io/cli/env) command +* the [use-node-version](https://pnpm.io/npmrc#use-node-version) setting +* the [pnpm.executionEnv.nodeVersion](https://pnpm.io/package_json#pnpmexecutionenvnodeversion) setting. + +## Unresolved Questions and Bikeshedding + +{{Write about any arbitrary decisions that need to be made (syntax, colors, formatting, minor UX decisions), and any questions for the proposal that have not been answered.}} + +{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} + From 744d806b72720697baf0e878e3ef061ee07832a5 Mon Sep 17 00:00:00 2001 From: Zoltan Kochan Date: Mon, 26 Aug 2024 03:01:24 +0200 Subject: [PATCH 2/5] add setting for disabling execution envs --- text/{0003-execution-env.md => 0003-execution-environment.md} | 2 ++ 1 file changed, 2 insertions(+) rename text/{0003-execution-env.md => 0003-execution-environment.md} (93%) diff --git a/text/0003-execution-env.md b/text/0003-execution-environment.md similarity index 93% rename from text/0003-execution-env.md rename to text/0003-execution-environment.md index 9201961..47349f7 100644 --- a/text/0003-execution-env.md +++ b/text/0003-execution-environment.md @@ -74,6 +74,8 @@ If we don't want to control the execution env of the published package, set the In this case, pnpm will remove the `executionEnv` setting from the `package.json` file on publish and the binary of the package will be executed with whatever runtime will be installed globally on the target machine. +Some environments might not want to allow pnpm to control the js runtime. For thes cases we need to support a setting that will instruct pnpm to ignore all the execution env settings: `ignore-execution-env=true`. + ## Rationale and Alternatives The alternative would be to use a third party tool for this (like Volta) but then we would have one more prerequisite for using pnpm. From 25a57c2154a0472a2991a10815089638c25f7a67 Mon Sep 17 00:00:00 2001 From: Zoltan Kochan Date: Mon, 26 Aug 2024 12:10:16 +0200 Subject: [PATCH 3/5] js=>jsRuntime --- text/0003-execution-environment.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/0003-execution-environment.md b/text/0003-execution-environment.md index 47349f7..9fffcc1 100644 --- a/text/0003-execution-environment.md +++ b/text/0003-execution-environment.md @@ -20,7 +20,7 @@ We will support a new field in `package.json`: `pnpm.executionEnv.js`. This fiel { "pnpm": { "executionEnv": { - "js": "node@20.16.0" + "jsRuntime": "node@20.16.0" } } } @@ -32,7 +32,7 @@ or { "pnpm": { "executionEnv": { - "js": "bun@1.1.26" + "jsRuntime": "bun@1.1.26" } } } @@ -44,7 +44,7 @@ or { "pnpm": { "executionEnv": { - "js": "deno@1.46.1" + "jsRuntime": "deno@1.46.1" } } } @@ -65,7 +65,7 @@ If we don't want to control the execution env of the published package, set the "bin": "bin.js", "pnpm": { "executionEnv": { - "js": "node@20.16.0", + "jsRuntime": "node@20.16.0", "localOnly": true } } From 95045097ae09ad726dd42f3b976e674c3b03bcae Mon Sep 17 00:00:00 2001 From: Zoltan Kochan Date: Mon, 26 Aug 2024 16:20:57 +0200 Subject: [PATCH 4/5] Update text/0003-execution-environment.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Khải --- text/0003-execution-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0003-execution-environment.md b/text/0003-execution-environment.md index 9fffcc1..ecaaa05 100644 --- a/text/0003-execution-environment.md +++ b/text/0003-execution-environment.md @@ -14,7 +14,7 @@ Running multiple versions of Node.js on the same computer isn't easy. Also, ther ## Detailed Explanation -We will support a new field in `package.json`: `pnpm.executionEnv.js`. This field will be similar to the `packageManager` field introduced by Corepack but will feature `@` instead. For example: +We will support a new field in `package.json`: `pnpm.executionEnv.jsRuntime`. This field will be similar to the `packageManager` field introduced by Corepack but will feature `@` instead. For example: ```json { From 98e052c5c8cd71df91d719ad9692cdb874ffe990 Mon Sep 17 00:00:00 2001 From: Zoltan Kochan Date: Tue, 27 Aug 2024 01:57:11 +0200 Subject: [PATCH 5/5] document alternative --- text/0003-execution-environment.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0003-execution-environment.md b/text/0003-execution-environment.md index ecaaa05..339f751 100644 --- a/text/0003-execution-environment.md +++ b/text/0003-execution-environment.md @@ -80,6 +80,8 @@ Some environments might not want to allow pnpm to control the js runtime. For th The alternative would be to use a third party tool for this (like Volta) but then we would have one more prerequisite for using pnpm. +Instead of introducing a new field, we could use the `engines` field for detecting what Node.js version should be used for running the bin file or building the package. However, the `engines` field is already used by other package managers and it is usually just sets a range with the lowest supported Node.js version. If we will use it for specifying exact versions, installations of the package with other package managers will fail, when `engine-strict` is set to `true`. + ## Implementation The implementation can leverage the logic that is already present in pnpm for the `pnpm env` command, the `pnpm.executionEnv.nodeVersion` setting, the `use-node-version` setting.