Commit 7bf3aa9d authored by Tomodachi94's avatar Tomodachi94
Browse files

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.
parent 2519871a

doc/languages-frameworks/javascript.section.md

+0 −87
Original line number Diff line number Diff line
@@ -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.<new-or-updated-package>

   ```



    To build against the latest stable Current Node.js version (e.g. 18.x):



    ```sh

    nix-build -A nodePackages_latest.<new-or-updated-package>

    ```



    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}

doc/redirects.json

+0 −9
Original line number Diff line number Diff line
@@ -3425,15 +3425,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"

  ],

pkgs/development/node-packages/README.md

+84 −1
Original line number Diff line number Diff line 
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.<new-or-updated-package>

   ```



    To build against the latest stable Current Node.js version (e.g. 18.x):



    ```sh

    nix-build -A nodePackages_latest.<new-or-updated-package>

    ```



    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/

```