Doc/importNpmLock: general improvements (#340019)

Co-authored-by: Valentin Gagarin <[email protected]>

Author: hsjobeki

doc/languages-frameworks/javascript.section.md

@@ -258,34 +258,79 @@ It returns a derivation with all `package-lock.json` dependencies downloaded int
 
 #### importNpmLock {#javascript-buildNpmPackage-importNpmLock}
 
-`importNpmLock` is a Nix function that requires the following optional arguments:
+This function replaces the npm dependency references in `package.json` and `package-lock.json` with paths to the Nix store.
+How each dependency is fetched can be customized with the `fetcherOpts` argument.
 
-- `npmRoot`: Path to package directory containing the source tree
+This is a simpler and more convenient alternative to [`fetchNpmDeps`](#javascript-buildNpmPackage-fetchNpmDeps) for managing npm dependencies in Nixpkgs.
+There is no need to specify a `hash`, since it relies entirely on the integrity hashes already present in the `package-lock.json` file.
+
+##### Inputs {#javascript-buildNpmPackage-inputs}
+
+- `npmRoot`: Path to package directory containing the source tree.
+  If this is omitted, the `package` and `packageLock` arguments must be specified instead.
 - `package`: Parsed contents of `package.json`
 - `packageLock`: Parsed contents of `package-lock.json`
 - `pname`: Package name
 - `version`: Package version
+- `fetcherOpts`: An attribute set of arguments forwarded to the underlying fetcher.
 
 It returns a derivation with a patched `package.json` & `package-lock.json` with all dependencies resolved to Nix store paths.
 
-This function is analogous to using `fetchNpmDeps`, but instead of specifying `hash` it uses metadata from `package.json` & `package-lock.json`.
+:::{.note}
+`npmHooks.npmConfigHook` cannot be used with `importNpmLock`.
+Use `importNpmLock.npmConfigHook` instead.
+:::
+
+:::{.example}
+
+##### `pkgs.importNpmLock` usage example {#javascript-buildNpmPackage-example}
+```nix
+{ buildNpmPackage, importNpmLock }:
+
+buildNpmPackage {
+  pname = "hello";
+  version = "0.1.0";
+  src = ./.;
+
+  npmDeps = importNpmLock {
+    npmRoot = ./.;
+  };
 
-Note that `npmHooks.npmConfigHook` cannot be used with `importNpmLock`. You will instead need to use `importNpmLock.npmConfigHook`:
+  npmConfigHook = importNpmLock.npmConfigHook;
+}
+```
+:::
+
+:::{.example}
+##### `pkgs.importNpmLock` usage example with `fetcherOpts` {#javascript-buildNpmPackage-example-fetcherOpts}
+
+`importNpmLock` uses the following fetchers:
+
+- `pkgs.fetchurl` for `http(s)` dependencies
+- `builtins.fetchGit` for `git` dependencies
+
+It is possible to provide additional arguments to individual fetchers as needed:
 
 ```nix
 { buildNpmPackage, importNpmLock }:
 
 buildNpmPackage {
   pname = "hello";
   version = "0.1.0";
+  src = ./.;
 
   npmDeps = importNpmLock {
     npmRoot = ./.;
+    fetcherOpts = {
+      # Pass 'curlOptsList' to 'pkgs.fetchurl' while fetching 'axios'
+      { "node_modules/axios" = { curlOptsList = [ "--verbose" ]; }; }
+    };
   };
 
   npmConfigHook = importNpmLock.npmConfigHook;
 }
 ```
+:::
 
 #### importNpmLock.buildNodeModules {#javascript-buildNpmPackage-importNpmLock.buildNodeModules}