diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md index 1d6cf2fb0edf..2b4df6f68457 100644 --- 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 = ""; + config, + lib, + pkgs, + ... +}: +{ + systemd.services.nix-daemon.environment.NPM_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" = ""; }` +: 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" = ""; }` + +: 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}