From 9092f5d587460ef695beee72eb521cbee30fb4bc Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Fri, 6 Sep 2024 10:17:19 +0200
Subject: [PATCH] Doc/importNpmLock: general improvements

---
 .../javascript.section.md                     | 42 +++++++++++++++++--
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md
index ef8b7a60e24550a..c7f2d6ef78d345d 100644
--- a/doc/languages-frameworks/javascript.section.md
+++ b/doc/languages-frameworks/javascript.section.md
@@ -258,26 +258,38 @@ It returns a derivation with all `package-lock.json` dependencies downloaded int
 
 #### importNpmLock {#javascript-buildNpmPackage-importNpmLock}
 
+The `importNpmLock` function is a simpler and more convenient alternative to `fetchNpmDeps` for managing NPM dependencies in Nix. Unlike `fetchNpmDeps`, there is no need to specify a `hash` when using `importNpmLock`. This function relies entirely on the integrity hashes already present in the `package-lock.json` file.
+
+Here's what `importNpmLock` does:
+
+- It processes the `package.json` and `package-lock.json` files from your NPM project.
+- It replaces the dependency references in these files with paths to the Nix store.
+- It allows you to customize how each dependency is fetched. See argument: `fetcherOpts`.
+
 `importNpmLock` is a Nix function that requires the following optional arguments:
 
-- `npmRoot`: Path to package directory containing the source tree
+- `npmRoot`: Path to package directory containing the source tree. If this is omited `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 that `npmHooks.npmConfigHook` cannot be used with `importNpmLock`. You will instead need to use `importNpmLock.npmConfigHook`:
+:::{.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 = ./.;
@@ -286,6 +298,28 @@ buildNpmPackage {
   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 as needed:
+
+```nix
+  # ... omited for clarity
+  npmDeps = importNpmLock {
+    npmRoot = ./.;
+    fetcherOpts = {
+      { "node_modules/axios" = { curlOptsList = [ "--verbose" ]; }; }
+    };
+  }
+```
+:::
 
 #### importNpmLock.buildNodeModules {#javascript-buildNpmPackage-importNpmLock.buildNodeModules}