Consolidate environment variables to a single, exhaustive list (and keep in parity with CLI)

jsejcksn commented 1 week ago

Currently, there are environment variables spread out across the web documentation — with differing collections of variables listed or duplicated on different pages, for example:

runtime > manual > basics > env_variables.md

[`runtime/manual/basics/env_variables.md`](https://github.com/denoland/docs/blob/4c157384017bd16bbeaea5bc74f24cdf02551676/runtime/manual/basics/env_variables.md) | name | description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DENO_AUTH_TOKENS | A semi-colon separated list of bearer tokens and hostnames to use when fetching remote modules from private repositories
(e.g. `abcde12345@deno.land;54321edcba@github.com`) | | DENO_CERT | Load certificate authority from PEM encoded file | | DENO_DIR | Set the cache directory | | DENO_INSTALL_ROOT | Set deno install's output directory (defaults to `$HOME/.deno/bin`) | | DENO_JOBS | Number of parallel workers used for the `--parallel` flag with the test subcommand.
Defaults to number of available CPUs. | | DENO_NO_PACKAGE_JSON | Disables auto-resolution of `package.json` | | DENO_NO_PROMPT | Set to disable permission prompts on access
(alternative to passing `--no-prompt` on invocation) | | DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available | | DENO_REPL_HISTORY | Set REPL history file path History file is disabled when the value is empty
(defaults to `$DENO_DIR/deno_history.txt`) | | DENO_TLS_CA_STORE | Comma-separated list of order dependent certificate stores.
Possible values: `system`, `mozilla`. Defaults to `mozilla`. | | DENO_V8_FLAGS | Set V8 command line options | | HTTP_PROXY | Proxy address for HTTP requests (module downloads, fetch) | | HTTPS_PROXY | Proxy address for HTTPS requests (module downloads, fetch) | | NO_COLOR | Set to disable color | | NO_PROXY | Comma-separated list of hosts which do not use a proxy (module downloads, fetch) | | NPM_CONFIG_REGISTRY | URL to use for the npm registry. |

runtime > manual > getting_started > setup_your_environment.md

[`runtime/manual/getting_started/setup_your_environment.md`](https://github.com/denoland/docs/blob/4c157384017bd16bbeaea5bc74f24cdf02551676/runtime/manual/getting_started/setup_your_environment.md) | name | description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DENO_AUTH_TOKENS | a list of authorization tokens which can be used to allow Deno to access remote private code. See the [Private modules and repositories](../advanced/private_repositories.md) section for more details. | | DENO_CERT | load a certificate authority from a PEM encoded file. This "overrides" the `--cert` option. See the [Proxies](/runtime/reference/cli/env_variables#proxies) section for more information. | | DENO_DIR | this will set the directory where cached information from the CLI is stored. This includes items like cached remote modules, cached transpiled modules, language server cache information and persisted data from local storage. This defaults to the operating system's default cache location and then under the `deno` path. | | DENO_INSTALL_ROOT | When using `deno install` where the installed scripts are stored. This defaults to `$HOME/.deno/bin`. | | DENO_NO_PACKAGE_JSON | Set to disable auto-resolution of package.json files. | | DENO_NO_PROMPT | Set to disable permission prompts on access (alternative to passing `--no-prompt` on invocation). | | DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available. | | DENO_TLS_CA_STORE | a list of certificate stores which will be used when establishing TLS connections. The available stores are `mozilla` and `system`. You can specify one, both or none. Certificate chains attempt to resolve in the same order in which you specify them. The default value is `mozilla`. The `mozilla` store will use the bundled Mozilla certs provided by [`webpki-roots`](https://crates.io/crates/webpki-roots). The `system` store will use your platform's [native certificate store](https://crates.io/crates/rustls-native-certs). The exact set of Mozilla certs will depend on the version of Deno you are using. If you specify no certificate stores, then no trust will be given to any TLS connection without also specifying `DENO_CERT` or `--cert` or specifying a specific certificate per TLS connection. | | DENO_WEBGPU_TRACE | The directory to use for WebGPU traces. | | HTTP_PROXY | The proxy address to use for HTTP requests. See the [Proxies](/runtime/reference/cli/env_variables#proxies) section for more information. | | HTTPS_PROXY | The proxy address to use for HTTPS requests. See the [Proxies](/runtime/reference/cli/env_variables#proxies) section for more information. | | NO_COLOR | If set, this will prevent the Deno CLI from sending ANSI color codes when writing to stdout and stderr. See the website [https://no-color.org](https://no-color.org/) for more information on this _de facto_ standard. The value of this flag can be accessed at runtime without permission to read the environment variables by checking the value of `Deno.noColor`. | | NO_PROXY | Indicates hosts which should bypass the proxy set in the other environment variables. See the [Proxies](/runtime/reference/cli/env_variables#proxies) section for more information. | | NPM_CONFIG_REGISTRY | The npm registry to use when loading modules via [npm specifiers](../node/npm_specifiers.md) |

runtime > reference > cli > env_variables.md

[`runtime/reference/cli/env_variables.md`](https://github.com/denoland/docs/blob/4c157384017bd16bbeaea5bc74f24cdf02551676/runtime/reference/cli/env_variables.md) | name | description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DENO_AUTH_TOKENS | A list of authorization tokens which can be used to allow Deno to access remote private code. See the [Private modules and repositories](../advanced/private_repositories.md) section for more details. | | DENO_CERT | Load a certificate authority from a PEM encoded file. This "overrides" the `--cert` option. See the [Proxies](#proxies) section for more information. | | DENO_DIR | this will set the directory where cached information from the CLI is stored. This includes items like cached remote modules, cached transpiled modules, language server cache information and persisted data from local storage. This defaults to the operating system's default cache location and then under the `deno` path. | | DENO_INSTALL_ROOT | When using `deno install` where the installed scripts are stored. This defaults to `$HOME/.deno/bin`. | | DENO_NO_PACKAGE_JSON | Set to disable auto-resolution of package.json files. | | DENO_NO_PROMPT | Set to disable permission prompts on access (alternative to passing `--no-prompt` on invocation). | | DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available. | | DENO_TLS_CA_STORE | A list of certificate stores which will be used when establishing TLS connections. The available stores are `mozilla` and `system`. You can specify one, both or none. Certificate chains attempt to resolve in the same order in which you specify them. The default value is `mozilla`. The `mozilla` store will use the bundled Mozilla certs provided by [`webpki-roots`](https://crates.io/crates/webpki-roots). The `system` store will use your platform's [native certificate store](https://crates.io/crates/rustls-native-certs). The exact set of Mozilla certs will depend on the version of Deno you are using. If you specify no certificate stores, then no trust will be given to any TLS connection without also specifying `DENO_CERT` or `--cert` or specifying a specific certificate per TLS connection. | | DENO_WEBGPU_TRACE | The directory to use for WebGPU traces. | | HTTP_PROXY | The proxy address to use for HTTP requests. See the [Proxies](#proxies) section for more information. | | HTTPS_PROXY | The proxy address to use for HTTPS requests. See the [Proxies](#proxies) section for more information. | | NO_COLOR | If set, this will prevent the Deno CLI from sending ANSI color codes when writing to stdout and stderr. See the website [https://no-color.org](https://no-color.org/) for more information on this _de facto_ standard. The value of this flag can be accessed at runtime without permission to read the environment variables by checking the value of `Deno.noColor`. | | NO_PROXY | Indicates hosts which should bypass the proxy set in the other environment variables. See the [Proxies](#proxies) section for more information. | | NPM_CONFIG_REGISTRY | The npm registry to use when loading modules via [npm specifiers](../node/npm_specifiers.md) |

Additionally, the Deno CLI help command lists the following environment variables:

CLI list from the help command:

| name | description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DENO_AUTH_TOKENS | A semi-colon separated list of bearer tokens and hostnames to use when fetching remote modules from private repositories (e.g. "abcde12345@deno.land;54321edcba@github.com") | | DENO_CERT | Load certificate authorities from PEM encoded file | | DENO_DIR | Set the cache directory | | DENO_FUTURE | Set to "1" to enable APIs that will take effect in Deno 2 | | DENO_INSTALL_ROOT | Set deno install's output directory (defaults to $HOME/.deno/bin) | | DENO_NO_PACKAGE_JSON | Disables auto-resolution of package.json | | DENO_NO_UPDATE_CHECK | Set to disable checking if a newer Deno version is available | | DENO_TLS_CA_STORE | Comma-separated list of order dependent certificate stores. Possible values: "system", "mozilla". (defaults to "mozilla") | | HTTP_PROXY | Proxy address for HTTP requests (module downloads, fetch) | | HTTPS_PROXY | Proxy address for HTTPS requests (module downloads, fetch) | | NO_COLOR | Set to disable color | | NO_PROXY | Comma-separated list of hosts which do not use a proxy (module downloads, fetch) | | NPM_CONFIG_REGISTRY | URL to use for the npm registry. |

Raw CLI stdout:

```txt % deno help --- snip --- Environment variables: DENO_AUTH_TOKENS A semi-colon separated list of bearer tokens and hostnames to use when fetching remote modules from private repositories (e.g. "abcde12345@deno.land;54321edcba@github.com") DENO_FUTURE Set to "1" to enable APIs that will take effect in Deno 2 DENO_CERT Load certificate authorities from PEM encoded file DENO_DIR Set the cache directory DENO_INSTALL_ROOT Set deno install's output directory (defaults to $HOME/.deno/bin) DENO_NO_PACKAGE_JSON Disables auto-resolution of package.json DENO_NO_UPDATE_CHECK Set to disable checking if a newer Deno version is available DENO_TLS_CA_STORE Comma-separated list of order dependent certificate stores. Possible values: "system", "mozilla". (defaults to "mozilla") HTTP_PROXY Proxy address for HTTP requests (module downloads, fetch) HTTPS_PROXY Proxy address for HTTPS requests (module downloads, fetch) NO_COLOR Set to disable color NO_PROXY Comma-separated list of hosts which do not use a proxy (module downloads, fetch) NPM_CONFIG_REGISTRY URL to use for the npm registry. --- snip --- ``` ```txt % deno --version deno 1.46.2 (stable, release, aarch64-apple-darwin) v8 12.9.202.5-rusty typescript 5.5.2 ```

Here's a juxtaposition of the variables from all of the lists above:

{
  "common": [
    "DENO_AUTH_TOKENS",
    "DENO_CERT",
    "DENO_DIR",
    "DENO_INSTALL_ROOT",
    "DENO_NO_PACKAGE_JSON",
    "DENO_NO_UPDATE_CHECK",
    "DENO_TLS_CA_STORE",
    "HTTP_PROXY",
    "HTTPS_PROXY",
    "NO_COLOR",
    "NO_PROXY",
    "NPM_CONFIG_REGISTRY"
  ],
  "differences": {
    "cli help command": [
      "DENO_FUTURE"
    ],
    "runtime/manual/basics/env_variables.md": [
      "DENO_JOBS",
      "DENO_NO_PROMPT",
      "DENO_REPL_HISTORY",
      "DENO_V8_FLAGS"
    ],
    "runtime/manual/getting_started/setup_your_environment.md": [
      "DENO_NO_PROMPT",
      "DENO_WEBGPU_TRACE"
    ],
    "runtime/reference/cli/env_variables.md": [
      "DENO_NO_PROMPT",
      "DENO_WEBGPU_TRACE"
    ]
  }
}

Script used to generate the comparison data:

`juxtapose.ts`: ```ts function compareBase(a: string, b: string): number { return a.localeCompare(b, "en-US", { sensitivity: "base" }); } const lists: Array<{ difference: Set; list: Set; name: string; }> = ([ ["cli help command", [ "DENO_AUTH_TOKENS", "DENO_CERT", "DENO_DIR", "DENO_FUTURE", "DENO_INSTALL_ROOT", "DENO_NO_PACKAGE_JSON", "DENO_NO_UPDATE_CHECK", "DENO_TLS_CA_STORE", "HTTP_PROXY", "HTTPS_PROXY", "NO_COLOR", "NO_PROXY", "NPM_CONFIG_REGISTRY", ]], ["runtime/manual/basics/env_variables.md", [ "DENO_AUTH_TOKENS", "DENO_CERT", "DENO_DIR", "DENO_INSTALL_ROOT", "DENO_JOBS", "DENO_NO_PACKAGE_JSON", "DENO_NO_PROMPT", "DENO_NO_UPDATE_CHECK", "DENO_REPL_HISTORY", "DENO_TLS_CA_STORE", "DENO_V8_FLAGS", "HTTP_PROXY", "HTTPS_PROXY", "NO_COLOR", "NO_PROXY", "NPM_CONFIG_REGISTRY", ]], ["runtime/manual/getting_started/setup_your_environment.md", [ "DENO_AUTH_TOKENS", "DENO_CERT", "DENO_DIR", "DENO_INSTALL_ROOT", "DENO_NO_PACKAGE_JSON", "DENO_NO_PROMPT", "DENO_NO_UPDATE_CHECK", "DENO_TLS_CA_STORE", "DENO_WEBGPU_TRACE", "HTTP_PROXY", "HTTPS_PROXY", "NO_COLOR", "NO_PROXY", "NPM_CONFIG_REGISTRY", ]], ["runtime/reference/cli/env_variables.md", [ "DENO_AUTH_TOKENS", "DENO_CERT", "DENO_DIR", "DENO_INSTALL_ROOT", "DENO_NO_PACKAGE_JSON", "DENO_NO_PROMPT", "DENO_NO_UPDATE_CHECK", "DENO_TLS_CA_STORE", "DENO_WEBGPU_TRACE", "HTTP_PROXY", "HTTPS_PROXY", "NO_COLOR", "NO_PROXY", "NPM_CONFIG_REGISTRY", ]], ] satisfies [name: string, list: string[]][]).sort(([a], [b]) => compareBase(a, b) ).map(([name, list]) => ({ difference: new Set(), list: new Set(list.sort(compareBase)), name, })); let common: Set = lists.values().next().value.list; for (const { list } of lists) common = common.intersection(list); for (const o of lists) o.difference = o.list.difference(common); console.log(JSON.stringify( { common: [...common], differences: Object.fromEntries( [...lists].map((o) => [o.name, [...o.difference]]), ), }, null, 2, )); ```

It will be helpful to unify the lists across all sources and keep them in parity.

I will create mirror of this issue in the CLI repository for tracking purposes and reference it here.

jsejcksn commented 1 week ago

Ref:

jsejcksn commented 5 days ago

I guess because the CLI now references the URL https://docs.deno.com/go/env-vars, this is the location that should display the consolidated list.

denoland / docs

Consolidate environment variables to a single, exhaustive list (and keep in parity with CLI) #784