Unverified Commit 71f01ce1 authored by Johannes Kirschbauer's avatar Johannes Kirschbauer Committed by GitHub
Browse files

Doc/importNpmLock: general improvements (#340019)

parent 086e6004
Loading
Loading
Loading
Loading
+49 −4
Original line number Diff line number Diff line
@@ -258,19 +258,58 @@ 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 }:
@@ -278,14 +317,20 @@ Note that `npmHooks.npmConfigHook` cannot be used with `importNpmLock`. You will
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}