nathan/nixpkgs
1
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2026-08-27 02:34:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: fix capitalization and use consistent terminology

Browse Source
This commit is contained in:
Enjeck C.
2026-07-26 18:00:45 +01:00
parent 5074d8679c
commit 8c33ba0fdb
1 changed files with 20 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
doc/languages-frameworks/javascript.section.md
View File

@@ -1,4 +1,4 @@
# Javascript {#language-javascript}
# JavaScript {#language-javascript}
## Introduction {#javascript-introduction}
@@ -13,12 +13,12 @@ Finally, some tool-specific instructions will be given.
If you find you are lacking inspiration for packaging JavaScript applications, the links below might prove useful.
Searching online for prior art can be helpful if you are running into solved problems.
### Github {#javascript-finding-examples-github}
### GitHub {#javascript-finding-examples-github}
- Searching Nix files for `yarnConfigHook`: <https://github.com/search?q=yarnConfigHook+language%3ANix&type=code>
- Searching just `flake.nix` files for `yarnConfigHook`: <https://github.com/search?q=yarnConfigHook+path%3A**%2Fflake.nix&type=code>
### Gitlab {#javascript-finding-examples-gitlab}
### GitLab {#javascript-finding-examples-gitlab}
- Searching Nix files for `yarnConfigHook`: <https://gitlab.com/search?scope=blobs&search=yarnConfigHook+extension%3Anix>
- Searching just `flake.nix` files for `yarnConfigHook`: <https://gitlab.com/search?scope=blobs&search=yarnConfigHook+filename%3Aflake.nix>
@@ -29,14 +29,14 @@ Searching online for prior art can be helpful if you are running into solved pro
The following principles are given in order of importance with potential exceptions.
### Try to use the same node version used upstream {#javascript-upstream-node-version}
### Use the same Node.js version as upstream {#javascript-upstream-node-version}
It is often not documented which node version is used upstream, but if it is, try to use the same version when packaging.
It is often not documented which Node.js version is used upstream, but if it is, try to use the same version when packaging.
This can be a problem if upstream is using the latest and greatest and you are trying to use an earlier version of node.
This can be a problem if upstream is using the latest and greatest and you are trying to use an earlier version of Node.js.
Some cryptic errors regarding V8 may appear.
### Try to respect the package manager originally used by upstream (and use the upstream lock file) {#javascript-upstream-package-manager}
### Use upstream's package manager and lock file {#javascript-upstream-package-manager}
A lock file (package-lock.json, yarn.lock...) is supposed to make reproducible installations of `node_modules` for each tool.
@@ -54,7 +54,7 @@ Exceptions to this rule are:
- When you encounter one of the bugs from a Nix tool. In each of the tool-specific instructions, known problems will be detailed. If you have a problem with a particular tool, then it's best to try another tool, even if this means you will have to re-create a lock file and commit it to Nixpkgs.
- Some lock files contain particular version of a package that has been pulled off npm for some reason. In that case, you can recreate upstream lock (by removing the original and `npm install`, `yarn`, ...) and commit this to nixpkgs.
### Try to use upstream package.json {#javascript-upstream-package-json}
### Use upstream `package.json` {#javascript-upstream-package-json}
Exceptions to this rule are:
@@ -84,7 +84,7 @@ Exceptions to this rule are:
You will still need to commit the modified version of the lock files, but at least the overrides are explicit for everyone to see.
### Using node_modules directly {#javascript-using-node_modules}
### Use `node_modules` directly {#javascript-using-node_modules}
Each tool has an abstraction to just build the node_modules (dependencies) directory.
You can always use the `stdenv.mkDerivation` with the node_modules to build the package (symlink the node_modules directory and then use the package build command).
@@ -173,7 +173,7 @@ sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
`fetchNpmDeps` is a Nix function that requires the following mandatory arguments:
- `src`: A directory / tarball with `package-lock.json` file
- `hash`: The output hash of the node dependencies defined in `package-lock.json`.
- `hash`: The output hash of the dependencies defined in `package-lock.json`.
It returns a derivation with all `package-lock.json` dependencies downloaded into `$out/`, usable as an npm cache.
@@ -195,7 +195,7 @@ There is no need to specify a `hash`, since it relies entirely on the integrity
- `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.
It returns a derivation with a patched `package.json` and `package-lock.json` with all dependencies resolved to Nix store paths.
:::{.note}
`npmHooks.npmConfigHook` cannot be used with `importNpmLock`.
@@ -291,7 +291,7 @@ pkgs.mkShell {
will create a development shell where a `node_modules` directory is created & packages symlinked to the Nix store when activated.
:::{.note}
Commands like `npm install` & `npm add` that write packages & executables need to be used with `--package-lock-only`.
Commands like `npm install` and `npm add` that write packages and executables need to be used with `--package-lock-only`.
This means `npm` installs dependencies by writing into `package-lock.json` without modifying the `node_modules` folder. Installation happens through reloading the devShell.
This might be best practice since it gives the `nix shell` virtually exclusive ownership over your `node_modules` folder.
@@ -439,7 +439,7 @@ Assuming the following directory structure, we can define `sourceRoot` and `pnpm
}
```
#### PNPM Workspaces {#javascript-pnpm-workspaces}
#### pnpm workspaces {#javascript-pnpm-workspaces}
If you need to use a PNPM workspace for your project, then set `pnpmWorkspaces = [ "<workspace project name 1>" "<workspace project name 2>" ]`, etc, in your `fetchPnpmDeps` call,
which will make PNPM only install dependencies for those workspace packages.
@@ -474,9 +474,9 @@ Usually, in such cases, you'd want to use `pnpm --filter=<pnpm workspace name> b
}
```
#### Additional PNPM Commands and settings {#javascript-pnpm-extraCommands}
#### Additional pnpm commands and settings {#javascript-pnpm-extraCommands}
If you require setting an additional PNPM configuration setting (such as `dedupe-peer-dependents` or similar),
If you require setting an additional pnpm configuration setting (such as `dedupe-peer-dependents` or similar),
set `prePnpmInstall` to the right commands to run. For example:
```nix
@@ -511,7 +511,7 @@ This is the version of the output of `fetchPnpmDeps`. New packages should use `4
When upgrading to a newer `fetcherVersion`, you need to regenerate the hash.
This variable ensures that we can make changes to the output of `fetchPnpmDeps` without breaking existing hashes.
Changes can include workarounds or bug fixes to existing PNPM issues.
Changes can include workarounds or bug fixes to existing pnpm issues.
##### Version history {#javascript-pnpm-fetcherVersion-versionHistory}
@@ -524,9 +524,9 @@ Version 3 is the minimum supported value. Versions 1 and 2 were removed in the 2
### Yarn {#javascript-yarn}
Yarn based projects use a `yarn.lock` file instead of a `package-lock.json` to pin dependencies.
Yarn-based projects use a `yarn.lock` file instead of a `package-lock.json` to pin dependencies.
To package yarn-based applications, you need to distinguish by the version pointers in the `yarn.lock` file. See the following sections.
To package Yarn-based applications, you need to distinguish by the version pointers in the `yarn.lock` file. See the following sections.
#### Yarn v1 {#javascript-yarn-v1}
@@ -718,7 +718,7 @@ If you are packaging something outside Nixpkgs, consider the following:
### npmlock2nix {#javascript-npmlock2nix}
[npmlock2nix](https://github.com/nix-community/npmlock2nix) aims at building `node_modules` without code generation. It hasn't reached v1 yet, the API might be subject to change.
[npmlock2nix](https://github.com/nix-community/npmlock2nix) aims at building `node_modules` without code generation. It hasn't reached v1 yet, the API may change.
#### Pitfalls {#javascript-npmlock2nix-pitfalls}
@@ -726,7 +726,7 @@ There are some [problems with npm v7](https://github.com/tweag/npmlock2nix/issue
### nix-npm-buildpackage {#javascript-nix-npm-buildpackage}
[nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage) aims at building `node_modules` without code generation. It hasn't reached v1 yet, the API might change. It supports both `package-lock.json` and yarn.lock.
[nix-npm-buildpackage](https://github.com/serokell/nix-npm-buildpackage) aims at building `node_modules` without code generation. It hasn't reached v1 yet, the API may change. It supports both `package-lock.json` and yarn.lock.
#### Pitfalls {#javascript-nix-npm-buildpackage-pitfalls}