From 43a7b34fadeae2c80acf6411468bae41b13f920f Mon Sep 17 00:00:00 2001 From: Tomodachi94 Date: Sat, 29 Nov 2025 20:25:21 -0800 Subject: [PATCH 1/2] doc/javascript: move nodePackages information back to README.md Adding new packages here is discouraged, for reasons enumerated in https://github.com/NixOS/nixpkgs/issues/229475, so let's move this (mostly developer-facing) documentation back into its original location in pkgs/development/node-packages/README.md. (cherry picked from commit 7bf3aa9d0da46f585c58f818bd718f116ca78128) --- .../javascript.section.md | 87 ------------------- doc/redirects.json | 9 -- pkgs/development/node-packages/README.md | 85 +++++++++++++++++- 3 files changed, 84 insertions(+), 97 deletions(-) diff --git a/doc/languages-frameworks/javascript.section.md b/doc/languages-frameworks/javascript.section.md index d19884154438..360124bbcdac 100644 --- a/doc/languages-frameworks/javascript.section.md +++ b/doc/languages-frameworks/javascript.section.md @@ -95,93 +95,6 @@ The node_modules abstraction can be also used to build some web framework fronte For an example of this see how [plausible](https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/web-apps/plausible/default.nix) is built. `mkYarnModules` to make the derivation containing node_modules. Then when building the frontend you can just symlink the node_modules directory. -## Javascript packages inside nixpkgs {#javascript-packages-nixpkgs} - -The [pkgs/development/node-packages](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages) folder contains a generated collection of [npm packages](https://npmjs.com/) that can be installed with the Nix package manager. - -As a rule of thumb, the package set should only provide _end-user_ software packages, such as command-line utilities. -Libraries should only be added to the package set if there is a non-npm package that requires it. - -When it is desired to use npm libraries in a development project, use the `node2nix` generator directly on the `package.json` configuration file of the project. - -The package set provides support for the official stable Node.js versions. -The latest stable LTS release in `nodePackages`, as well as the latest stable current release in `nodePackages_latest`. - -If your package uses native addons, you need to examine what kind of native build system it uses. Here are some examples: - -- `node-gyp` -- `node-gyp-builder` -- `node-pre-gyp` - -After you have identified the correct system, you need to override your package expression while adding in build system as a build input. -For example, `dat` requires `node-gyp-build`, so we override its expression in [pkgs/development/node-packages/overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/overrides.nix): - -```nix -{ - dat = prev.dat.override (oldAttrs: { - buildInputs = [ - final.node-gyp-build - pkgs.libtool - pkgs.autoconf - pkgs.automake - ]; - meta = oldAttrs.meta // { - broken = since "12"; - }; - }); -} -``` - -### Adding and updating JavaScript packages in Nixpkgs {#javascript-adding-or-updating-packages} - -To add a package from npm to Nixpkgs: - -1. Modify [pkgs/development/node-packages/node-packages.json](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/node-packages.json) to add, update or remove package entries to have it included in `nodePackages` and `nodePackages_latest`. -2. Run the script: - - ```sh - ./pkgs/development/node-packages/generate.sh - ``` - -3. Build your new package to test your changes: - - ```sh - nix-build -A nodePackages. - ``` - - To build against the latest stable Current Node.js version (e.g. 18.x): - - ```sh - nix-build -A nodePackages_latest. - ``` - - If the package doesn't build, you may need to add an override as explained above. -4. If the package's name doesn't match any of the executables it provides, add an entry in [pkgs/development/node-packages/main-programs.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/main-programs.nix). This will be the case for all scoped packages, e.g., `@angular/cli`. -5. Add and commit all modified and generated files. - -For more information about the generation process, consult the [README.md](https://github.com/svanderburg/node2nix) file of the `node2nix` tool. - -To update npm packages in Nixpkgs, run the same `generate.sh` script: - -```sh -./pkgs/development/node-packages/generate.sh -``` - -#### Git protocol error {#javascript-git-error} - -Some packages may have Git dependencies from GitHub specified with `git://`. -GitHub has [disabled unencrypted Git connections](https://github.blog/2021-09-01-improving-git-protocol-security-github/#no-more-unauthenticated-git), so you may see the following error when running the generate script: - -``` -The unauthenticated git protocol on port 9418 is no longer supported -``` - -Use the following Git configuration to resolve the issue: - -```sh -git config --global url."https://github.com/".insteadOf git://github.com/ -``` - ## Tool-specific instructions {#javascript-tool-specific} ### buildNpmPackage {#javascript-buildNpmPackage} diff --git a/doc/redirects.json b/doc/redirects.json index 2570eec68018..23a06c25d493 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -3401,15 +3401,6 @@ "javascript-using-node_modules": [ "index.html#javascript-using-node_modules" ], - "javascript-packages-nixpkgs": [ - "index.html#javascript-packages-nixpkgs" - ], - "javascript-adding-or-updating-packages": [ - "index.html#javascript-adding-or-updating-packages" - ], - "javascript-git-error": [ - "index.html#javascript-git-error" - ], "javascript-tool-specific": [ "index.html#javascript-tool-specific" ], diff --git a/pkgs/development/node-packages/README.md b/pkgs/development/node-packages/README.md index 38d1ff2018c4..13d083f21d0a 100644 --- a/pkgs/development/node-packages/README.md +++ b/pkgs/development/node-packages/README.md @@ -1 +1,84 @@ -Moved to [/doc/languages-frameworks/javascript.section.md](/doc/languages-frameworks/javascript.section.md) +This folder contains a generated collection of [npm packages](https://npmjs.com/) that can be installed with the Nix package manager. + +As a rule of thumb, the package set should only provide _end-user_ software packages, such as command-line utilities. +Libraries should only be added to the package set if there is a non-npm package that requires it. + +When it is desired to use npm libraries in a development project, use the `node2nix` generator directly on the `package.json` configuration file of the project. + +The package set provides support for the official stable Node.js versions. +The latest stable LTS release in `nodePackages`, as well as the latest stable current release in `nodePackages_latest`. + +If your package uses native addons, you need to examine what kind of native build system it uses. Here are some examples: + +- `node-gyp` +- `node-gyp-builder` +- `node-pre-gyp` + +After you have identified the correct system, you need to override your package expression while adding in build system as a build input. +For example, `dat` requires `node-gyp-build`, so we override its expression in [pkgs/development/node-packages/overrides.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/overrides.nix): + +```nix +{ + dat = prev.dat.override (oldAttrs: { + buildInputs = [ + final.node-gyp-build + pkgs.libtool + pkgs.autoconf + pkgs.automake + ]; + meta = oldAttrs.meta // { + broken = since "12"; + }; + }); +} +``` + +### Adding and updating JavaScript packages in Nixpkgs + +To add a package from npm to Nixpkgs: + +1. Modify [pkgs/development/node-packages/node-packages.json](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/node-packages.json) to add, update or remove package entries to have it included in `nodePackages` and `nodePackages_latest`. +2. Run the script: + + ```sh + ./pkgs/development/node-packages/generate.sh + ``` + +3. Build your new package to test your changes: + + ```sh + nix-build -A nodePackages. + ``` + + To build against the latest stable Current Node.js version (e.g. 18.x): + + ```sh + nix-build -A nodePackages_latest. + ``` + + If the package doesn't build, you may need to add an override as explained above. +4. If the package's name doesn't match any of the executables it provides, add an entry in [pkgs/development/node-packages/main-programs.nix](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/node-packages/main-programs.nix). This will be the case for all scoped packages, e.g., `@angular/cli`. +5. Add and commit all modified and generated files. + +For more information about the generation process, consult the [README.md](https://github.com/svanderburg/node2nix) file of the `node2nix` tool. + +To update npm packages in Nixpkgs, run the same `generate.sh` script: + +```sh +./pkgs/development/node-packages/generate.sh +``` + +#### Git protocol error + +Some packages may have Git dependencies from GitHub specified with `git://`. +GitHub has [disabled unencrypted Git connections](https://github.blog/2021-09-01-improving-git-protocol-security-github/#no-more-unauthenticated-git), so you may see the following error when running the generate script: + +``` +The unauthenticated git protocol on port 9418 is no longer supported +``` + +Use the following Git configuration to resolve the issue: + +```sh +git config --global url."https://github.com/".insteadOf git://github.com/ +``` From ff52f8241e4219f8864a5402e5ceccb3ce606164 Mon Sep 17 00:00:00 2001 From: Tomodachi94 Date: Sat, 29 Nov 2025 20:31:23 -0800 Subject: [PATCH 2/2] nodePackages: update docs to discourage adding new packages (cherry picked from commit a8ea7b38dac6de7fd22d4f0c102f4f4cdb13028d) --- pkgs/development/node-packages/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/pkgs/development/node-packages/README.md b/pkgs/development/node-packages/README.md index 13d083f21d0a..8f82ad73a0fc 100644 --- a/pkgs/development/node-packages/README.md +++ b/pkgs/development/node-packages/README.md @@ -1,3 +1,7 @@ +> [!IMPORTANT] +> There is currently an active project to [remove packages from `nodePackages`](https://github.com/NixOS/nixpkgs/issues/229475). +> Please consider adding new packages using [another method](https://nixos.org/manual/nixpkgs/unstable/#javascript-tool-specific). + This folder contains a generated collection of [npm packages](https://npmjs.com/) that can be installed with the Nix package manager. As a rule of thumb, the package set should only provide _end-user_ software packages, such as command-line utilities.