doc: refactored argument documention by using definition lists

2026-06-05 21:03:40 +00:00 · 2025-05-16 11:33:47 +02:00
parent c88d10c806
commit 2857128ddd
1 changed files with 117 additions and 38 deletions
--- a/doc/languages-frameworks/javascript.section.md
+++ b/doc/languages-frameworks/javascript.section.md
@@ -899,35 +899,48 @@ This works as follows:
 The `buildDenoDeps` derivation is in `passthru`, so it can be accessed from a `buildDenoPackage` derivation with `.denoDeps`

 Related options:
-* `denoDepsHash`: The output hash of the `buildDenoDeps` fixed output derivation.
-* `denoInstallFlags`: Flags passed to `deno install`.
-Defaults to `[ "--allow-scripts" "--frozen" ]` for `buildDenoDeps`
-and `[ "--allow-scripts" "--frozen" "--cached-only" ]` for `buildDenoPackage`
+
+*`denoDepsHash`* (String)
+
+: The output hash of the `buildDenoDeps` fixed output derivation.
+
+*`denoInstallFlags`* (Array of strings; optional)
+
+: The Flags passed to `deno install`.
+
+: _Default:_ `[ "--allow-scripts" "--frozen" ]` for `buildDenoDeps`
+: _Default:_ `[ "--allow-scripts" "--frozen" "--cached-only" ]` for `buildDenoPackage`

 #### Private registries {#javascript-buildDenoPackage-private-registries}
 There are currently 2 options, which enable the use of private registries in a `buildDenoPackage` derivation.

-**`denoDepsImpureEnvVars`**:
+*`denoDepsImpureEnvVars`* (Array of strings; optional)

-A list of strings, which are names of impure environment variables passed to the `buildDenoDeps` derivation.
-They are forwarded to `deno install`.
+: Names of impure environment variables passed to the `buildDenoDeps` derivation. They are forwarded to `deno install`.

-It can be used to set tokens for private NPM registries (in a `.npmrc` file).
+: _Example:_ `[ "NPM_TOKEN" ]`

-Example: `[ "NPM_TOKEN" ]`
+: It can be used to set tokens for private NPM registries (in a `.npmrc` file).

-In a single-user installation of Nix, you can put the variables into the environment, when running the nix build.
+: In a single-user installation of Nix, you can put the variables into the environment, when running the nix build.

-In multi-user installations of Nix, it's necessary to set the environment variables in the nix-daemon, probably with systemd.
+: In multi-user installations of Nix, it's necessary to set the environment variables in the nix-daemon, probably with systemd.

 :::{.example}

 ##### configure nix-daemon {#javascript-buildDenoPackage-private-registries-daemon-example}
-In NixOS' `configuration.nix`:
+In NixOS:

 ```nix
+# configuration.nix
 {
-   systemd.services.nix-daemon.environment.NPM_TOKEN = "<token>";
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+{
+  systemd.services.nix-daemon.environment.NPM_TOKEN = "<token>";
 }
 ```

@@ -941,12 +954,13 @@ $ sudo systemctl restart nix-daemon

 :::

-**`denoDepsInjectedEnvVars`**:
+*`denoDepsInjectedEnvVars`* (Attrset; optional)

-An attribute set with environment variables as key value pairs. Example: `{ "NPM_TOKEN" = "<token>"; }`
+: Environment variables as key value pairs. They are forwarded to `deno install`.

-They are forwarded to `deno install`.
-It can be used to set tokens for private NPM registries (in a `.npmrc` file).
+: _Example:_ `{ "NPM_TOKEN" = "<token>"; }`
+
+: It can be used to set tokens for private NPM registries (in a `.npmrc` file).
 You could pass these tokens from the Nix CLI with `--arg`,
 however this can hurt the reproducibility of your builds and such an injected
 token will also need to be injected in every build that depends on this build.
@@ -962,6 +976,12 @@ token will also need to be injected in every build that depends on this build.

 :::

+::: {.caution}
+
+Hardcoding a token into your NixOS configuration or some other nix build, will as a consequence write that token into `/nix/store`, which is considered world readable.
+
+:::
+
 ::: {.note}
 Neither approach is ideal. For `buildNpmPackage`, there exists a third
 option called `sourceOverrides`, which allows the user to inject Nix packages into
@@ -983,30 +1003,58 @@ or the `name` attribute of the derivation.

 Related options:

-* `hostPlatform`: The [host platform](#ssec-cross-platform-parameters) the binary is built for. Defaults to `builtins.currentSystem`.
+*`hostPlatform`* (String; optional)

-  Supported values:
+: The [host platform](#ssec-cross-platform-parameters) the binary is built for.
+
+: _Default:_ `builtins.currentSystem`.
+
+: _Supported values:_
  - `"x86_64-darwin"`
  - `"aarch64-darwin"`
  - `"x86_64-linux"`
  - `"aarch64-linux"`
-* `denoCompileFlags`: Flags passed to `deno compile`.
-* `binaryEntrypointPath`: If not `null`, create a binary using the specified path as the entrypoint,
-copy it to `$out/bin` in `installPhase`. It's prefixed by `denoWorkspacePath`, if using workspaces.
-* `denortPackage`: The package used as the Deno runtime, which is bundled with the JavaScript code to create the binary.
-Defaults to `pkgs.denort`. Don't use `pkgs.deno` for this, since that is the full Deno CLI, with all the development tooling.
-If you're cross compiling, this needs to be the `denort` of the `hostPlatform`.
+
+*`denoCompileFlags`* (Array of string; optional)
+
+: Flags passed to `deno compile`.
+
+*`binaryEntrypointPath`* (String or null; optional)
+
+: If not `null`, a binary is created using the specified path as the entry point.
+The binary is copied to `$out/bin` in the `installPhase`.
+
+: _Default:_ `null`
+
+: It's prefixed by `denoWorkspacePath`.
+
+*`denortPackage`* (Derivation; optional)
+
+: The package used as the Deno runtime, which is bundled with the JavaScript code to create the binary.
+
+: _Default:_ `pkgs.denort`
+
+: Don't use `pkgs.deno` for this, since that is the full Deno CLI, with all the development tooling.
+
+: If you're cross compiling, this needs to be the `denort` of the `hostPlatform`.

 ::: {.note}
 The binary will be dynamically linked and not executable on NixOS without [nix-ld](https://github.com/nix-community/nix-ld)
 or [other methods](https://unix.stackexchange.com/questions/522822/different-methods-to-run-a-non-nixos-executable-on-nixos).

 ```nix
+# configuration.nix
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
 {
  programs.nix-ld.enable = true;
  programs.nix-ld.libraries = with pkgs; [
-      glibc
-      gcc-unwrapped
+    glibc
+    gcc-unwrapped
  ];
 }
 ```
@@ -1025,7 +1073,7 @@ buildDenoPackage {
  denoDepsHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA";
  src = pkgs.nix-gitignore.gitignoreSource [ ] ./.;
  binaryEntrypointPath = "main.ts";
-};
+}
 ```

 :::
@@ -1036,9 +1084,24 @@ Instead of compiling to a binary, `deno task` can be executed inside the build
 to produce some artifact, which can then be copied out in the `installPhase`.

 Related options:
-* `denoTaskScript`: The task in `deno.json` that's executed with `deno task`. Defaults to `"build"`.
-* `denoTaskFlags`: Flags passed to `deno task`.
-* `denoTaskPrefix` & `denoTaskSuffix`: Unquoted strings surrounding `deno task`. For example to pipe stdout to a file.
+
+*`denoTaskScript`* (String; optional)
+
+: The task in `deno.json` that's executed with `deno task`.
+
+: _Default:_ `"build"`
+
+*`denoTaskFlags`* (Array of strings; optional)
+
+: The flags passed to `deno task`.
+
+*`denoTaskPrefix`* (String; optional)
+
+: An unquoted string injected before `deno task`.
+
+*`denoTaskSuffix`* (String; optional)
+
+: An unquoted string injected after `deno task` and all its flags. For example to pipe stdout to a file.

 :::{.example}

@@ -1065,7 +1128,7 @@ buildDenoPackage {
  installPhase = ''
    cp ./out.txt $out
  '';
-};
+}
 ```

 :::
@@ -1074,7 +1137,7 @@ buildDenoPackage {

 Deno's workspaces are supported.

-To make them work, the whole project needs to added as source, since the `deno.lock`
+To make them work, the whole project needs to be added as source, since the `deno.lock`
 is always in the root of the project and contains all dependencies.

 This means a build with only the required dependencies of a workspace is not possible.
@@ -1088,7 +1151,10 @@ When [compiling to a binary](#javascript-buildDenoPackage-compile-to-binary),
 `binaryEntrypointPath` is prefixed by `denoWorkspacePath`.

 Related options:
-  * `denoWorkspacePath`: Path to a workspace.
+
+*`denoWorkspacePath`* (String; optional)
+
+: The path to a workspace.

 :::{.example}

@@ -1103,7 +1169,10 @@ rec {
    denoDepsHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
    src = pkgs.nix-gitignore.gitignoreSource [ ] ./.;
    denoWorkspacePath = "./sub1";
-    denoTaskFlags = ["--text" "sub1"];
+    denoTaskFlags = [
+      "--text"
+      "sub1"
+    ];
    denoTaskSuffix = ">out.txt";
    installPhase = ''
      cp out.txt $out
@@ -1125,9 +1194,19 @@ rec {

 #### Other Options {#javascript-buildDenoPackage-other-options}

-  * `denoDir`: Set `DENO_DIR` to this value and use it for all `deno` commands
-  * `denoFlags`: Flags passed to all `deno` commands.
-  * `denoPackage`: The Deno CLI used for all `deno` commands inside the build.
+*`denoDir`* (String; optional)
+
+: `DENO_DIR` will be set to this value for all `deno` commands.
+
+*`denoFlags`* (Array of string; optional)
+
+: The flags passed to all `deno` commands.
+
+*`denoPackage`* (Derivation; optional)
+
+: The Deno CLI used for all `deno` commands inside the build.
+
+: _Default:_ `pkgs.deno`

 ## Outside Nixpkgs {#javascript-outside-nixpkgs}