pyrox.dev
1# Javascript {#language-javascript}
2
3## Introduction {#javascript-introduction}
4
5This contains instructions on how to package javascript applications.
6
7The various tools available will be listed in the [tools-overview](#javascript-tools-overview).
8Some general principles for packaging will follow.
9Finally some tool specific instructions will be given.
10
11## Getting unstuck / finding code examples {#javascript-finding-examples}
12
13If you find you are lacking inspiration for packaging javascript applications, the links below might prove useful.
14Searching online for prior art can be helpful if you are running into solved problems.
15
16### Github {#javascript-finding-examples-github}
17
18- Searching Nix files for `mkYarnPackage`: <https://github.com/search?q=mkYarnPackage+language%3ANix&type=code>
19- Searching just `flake.nix` files for `mkYarnPackage`: <https://github.com/search?q=mkYarnPackage+path%3A**%2Fflake.nix&type=code>
20
21### Gitlab {#javascript-finding-examples-gitlab}
22
23- Searching Nix files for `mkYarnPackage`: <https://gitlab.com/search?scope=blobs&search=mkYarnPackage+extension%3Anix>
24- Searching just `flake.nix` files for `mkYarnPackage`: <https://gitlab.com/search?scope=blobs&search=mkYarnPackage+filename%3Aflake.nix>
25
26## Tools overview {#javascript-tools-overview}
27
28## General principles {#javascript-general-principles}
29
30The following principles are given in order of importance with potential exceptions.
31
32### Try to use the same node version used upstream {#javascript-upstream-node-version}
33
34It is often not documented which node version is used upstream, but if it is, try to use the same version when packaging.
35
36This can be a problem if upstream is using the latest and greatest and you are trying to use an earlier version of node.
37Some cryptic errors regarding V8 may appear.
38
39### Try to respect the package manager originally used by upstream (and use the upstream lock file) {#javascript-upstream-package-manager}
40
41A lock file (package-lock.json, yarn.lock...) is supposed to make reproducible installations of `node_modules` for each tool.
42
43Guidelines of package managers, recommend to commit those lock files to the repos.
44If a particular lock file is present, it is a strong indication of which package manager is used upstream.
45
46It's better to try to use a Nix tool that understand the lock file.
47Using a different tool might give you hard to understand error because different packages have been installed.
48An example of problems that could arise can be found [here](https://github.com/NixOS/nixpkgs/pull/126629).
49Upstream use npm, but this is an attempt to package it with `yarn2nix` (that uses yarn.lock).
50
51Using a different tool forces to commit a lock file to the repository.
52Those files are fairly large, so when packaging for nixpkgs, this approach does not scale well.
53
54Exceptions to this rule are:
55
56- 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 recreate a lock file and commit it to nixpkgs. In general `yarn2nix` has less known problems and so a simple search in nixpkgs will reveal many yarn.lock files committed.
57- 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.
58- The only tool that supports workspaces (a feature of npm that helps manage sub-directories with different package.json from a single top level package.json) is `yarn2nix`. If upstream has workspaces you should try `yarn2nix`.
59
60### Try to use upstream package.json {#javascript-upstream-package-json}
61
62Exceptions to this rule are:
63
64- Sometimes the upstream repo assumes some dependencies be installed globally. In that case you can add them manually to the upstream package.json (`yarn add xxx` or `npm install xxx`, ...). Dependencies that are installed locally can be executed with `npx` for CLI tools. (e.g. `npx postcss ...`, this is how you can call those dependencies in the phases).
65- Sometimes there is a version conflict between some dependency requirements. In that case you can fix a version by removing the `^`.
66- Sometimes the script defined in the package.json does not work as is. Some scripts for example use CLI tools that might not be available, or cd in directory with a different package.json (for workspaces notably). In that case, it's perfectly fine to look at what the particular script is doing and break this down in the phases. In the build script you can see `build:*` calling in turns several other build scripts like `build:ui` or `build:server`. If one of those fails, you can try to separate those into,
67
68 ```sh
69 yarn build:ui
70 yarn build:server
71 # OR
72 npm run build:ui
73 npm run build:server
74 ```
75
76 when you need to override a package.json. It's nice to use the one from the upstream source and do some explicit override. Here is an example:
77
78 ```nix
79 {
80 patchedPackageJSON = final.runCommand "package.json" { } ''
81 ${jq}/bin/jq '.version = "0.4.0" |
82 .devDependencies."@jsdoc/cli" = "^0.2.5"
83 ${sonar-src}/package.json > $out
84 '';
85 }
86 ```
87
88 You will still need to commit the modified version of the lock files, but at least the overrides are explicit for everyone to see.
89
90### Using node_modules directly {#javascript-using-node_modules}
91
92Each tool has an abstraction to just build the node_modules (dependencies) directory.
93You 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).
94The node_modules abstraction can be also used to build some web framework frontends.
95For 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.
96Then when building the frontend you can just symlink the node_modules directory.
97
98## Javascript packages inside nixpkgs {#javascript-packages-nixpkgs}
99
100The [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.
101
102As a rule of thumb, the package set should only provide _end user_ software packages, such as command-line utilities.
103Libraries should only be added to the package set if there is a non-npm package that requires it.
104
105When 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.
106
107The package set provides support for the official stable Node.js versions.
108The latest stable LTS release in `nodePackages`, as well as the latest stable current release in `nodePackages_latest`.
109
110If your package uses native addons, you need to examine what kind of native build system it uses. Here are some examples:
111
112- `node-gyp`
113- `node-gyp-builder`
114- `node-pre-gyp`
115
116After you have identified the correct system, you need to override your package expression while adding in build system as a build input.
117For 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):
118
119```nix
120 {
121 dat = prev.dat.override (oldAttrs: {
122 buildInputs = [ final.node-gyp-build pkgs.libtool pkgs.autoconf pkgs.automake ];
123 meta = oldAttrs.meta // { broken = since "12"; };
124 });
125 }
126```
127
128### Adding and Updating Javascript packages in nixpkgs {#javascript-adding-or-updating-packages}
129
130To add a package from npm to nixpkgs:
131
1321. 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`.
1332. Run the script:
134
135 ```sh
136 ./pkgs/development/node-packages/generate.sh
137 ```
138
1393. Build your new package to test your changes:
140
141 ```sh
142 nix-build -A nodePackages.<new-or-updated-package>
143 ```
144
145 To build against the latest stable Current Node.js version (e.g. 18.x):
146
147 ```sh
148 nix-build -A nodePackages_latest.<new-or-updated-package>
149 ```
150
151 If the package doesn't build, you may need to add an override as explained above.
1524. 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`.
1535. Add and commit all modified and generated files.
154
155For more information about the generation process, consult the [README.md](https://github.com/svanderburg/node2nix) file of the `node2nix` tool.
156
157To update npm packages in nixpkgs, run the same `generate.sh` script:
158
159```sh
160./pkgs/development/node-packages/generate.sh
161```
162
163#### Git protocol error {#javascript-git-error}
164
165Some packages may have Git dependencies from GitHub specified with `git://`.
166GitHub 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:
167
168```
169The unauthenticated git protocol on port 9418 is no longer supported
170```
171
172Use the following Git configuration to resolve the issue:
173
174```sh
175git config --global url."https://github.com/".insteadOf git://github.com/
176```
177
178## Tool specific instructions {#javascript-tool-specific}
179
180### buildNpmPackage {#javascript-buildNpmPackage}
181
182`buildNpmPackage` allows you to package npm-based projects in Nixpkgs without the use of an auto-generated dependencies file (as used in [node2nix](#javascript-node2nix)).
183It works by utilizing npm's cache functionality -- creating a reproducible cache that contains the dependencies of a project, and pointing npm to it.
184
185Here's an example:
186
187```nix
188{ lib, buildNpmPackage, fetchFromGitHub }:
189
190buildNpmPackage rec {
191 pname = "flood";
192 version = "4.7.0";
193
194 src = fetchFromGitHub {
195 owner = "jesec";
196 repo = pname;
197 rev = "v${version}";
198 hash = "sha256-BR+ZGkBBfd0dSQqAvujsbgsEPFYw/ThrylxUbOksYxM=";
199 };
200
201 npmDepsHash = "sha256-tuEfyePwlOy2/mOPdXbqJskO6IowvAP4DWg8xSZwbJw=";
202
203 # The prepack script runs the build script, which we'd rather do in the build phase.
204 npmPackFlags = [ "--ignore-scripts" ];
205
206 NODE_OPTIONS = "--openssl-legacy-provider";
207
208 meta = {
209 description = "A modern web UI for various torrent clients with a Node.js backend and React frontend";
210 homepage = "https://flood.js.org";
211 license = lib.licenses.gpl3Only;
212 maintainers = with lib.maintainers; [ winter ];
213 };
214}
215```
216
217In the default `installPhase` set by `buildNpmPackage`, it uses `npm pack --json --dry-run` to decide what files to install in `$out/lib/node_modules/$name/`, where `$name` is the `name` string defined in the package's `package.json`.
218Additionally, the `bin` and `man` keys in the source's `package.json` are used to decide what binaries and manpages are supposed to be installed.
219If these are not defined, `npm pack` may miss some files, and no binaries will be produced.
220
221#### Arguments {#javascript-buildNpmPackage-arguments}
222
223* `npmDepsHash`: The output hash of the dependencies for this project. Can be calculated in advance with [`prefetch-npm-deps`](#javascript-buildNpmPackage-prefetch-npm-deps).
224* `makeCacheWritable`: Whether to make the cache writable prior to installing dependencies. Don't set this unless npm tries to write to the cache directory, as it can slow down the build.
225* `npmBuildScript`: The script to run to build the project. Defaults to `"build"`.
226* `npmWorkspace`: The workspace directory within the project to build and install.
227* `dontNpmBuild`: Option to disable running the build script. Set to `true` if the package does not have a build script. Defaults to `false`. Alternatively, setting `buildPhase` explicitly also disables this.
228* `dontNpmInstall`: Option to disable running `npm install`. Defaults to `false`. Alternatively, setting `installPhase` explicitly also disables this.
229* `npmFlags`: Flags to pass to all npm commands.
230* `npmInstallFlags`: Flags to pass to `npm ci`.
231* `npmBuildFlags`: Flags to pass to `npm run ${npmBuildScript}`.
232* `npmPackFlags`: Flags to pass to `npm pack`.
233* `npmPruneFlags`: Flags to pass to `npm prune`. Defaults to the value of `npmInstallFlags`.
234* `makeWrapperArgs`: Flags to pass to `makeWrapper`, added to executable calling the generated `.js` with `node` as an interpreter. These scripts are defined in `package.json`.
235* `nodejs`: The `nodejs` package to build against, using the corresponding `npm` shipped with that version of `node`. Defaults to `pkgs.nodejs`.
236* `npmDeps`: The dependencies used to build the npm package. Especially useful to not have to recompute workspace depedencies.
237
238#### prefetch-npm-deps {#javascript-buildNpmPackage-prefetch-npm-deps}
239
240`prefetch-npm-deps` is a Nixpkgs package that calculates the hash of the dependencies of an npm project ahead of time.
241
242```console
243$ ls
244package.json package-lock.json index.js
245$ prefetch-npm-deps package-lock.json
246...
247sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
248```
249
250#### fetchNpmDeps {#javascript-buildNpmPackage-fetchNpmDeps}
251
252`fetchNpmDeps` is a Nix function that requires the following mandatory arguments:
253
254- `src`: A directory / tarball with `package-lock.json` file
255- `hash`: The output hash of the node dependencies defined in `package-lock.json`.
256
257It returns a derivation with all `package-lock.json` dependencies downloaded into `$out/`, usable as an npm cache.
258
259#### importNpmLock {#javascript-buildNpmPackage-importNpmLock}
260
261`importNpmLock` is a Nix function that requires the following optional arguments:
262
263- `npmRoot`: Path to package directory containing the source tree
264- `package`: Parsed contents of `package.json`
265- `packageLock`: Parsed contents of `package-lock.json`
266- `pname`: Package name
267- `version`: Package version
268
269It returns a derivation with a patched `package.json` & `package-lock.json` with all dependencies resolved to Nix store paths.
270
271This function is analogous to using `fetchNpmDeps`, but instead of specifying `hash` it uses metadata from `package.json` & `package-lock.json`.
272
273Note that `npmHooks.npmConfigHook` cannot be used with `importNpmLock`. You will instead need to use `importNpmLock.npmConfigHook`:
274
275```nix
276{ buildNpmPackage, importNpmLock }:
277
278buildNpmPackage {
279 pname = "hello";
280 version = "0.1.0";
281
282 npmDeps = importNpmLock {
283 npmRoot = ./.;
284 };
285
286 npmConfigHook = importNpmLock.npmConfigHook;
287}
288```
289
290### corepack {#javascript-corepack}
291
292This package puts the corepack wrappers for pnpm and yarn in your PATH, and they will honor the `packageManager` setting in the `package.json`.
293
294### node2nix {#javascript-node2nix}
295
296#### Preparation {#javascript-node2nix-preparation}
297
298You will need to generate a Nix expression for the dependencies. Don't forget the `-l package-lock.json` if there is a lock file. Most probably you will need the `--development` to include the `devDependencies`
299
300So the command will most likely be:
301```sh
302node2nix --development -l package-lock.json
303```
304
305See `node2nix` [docs](https://github.com/svanderburg/node2nix) for more info.
306
307#### Pitfalls {#javascript-node2nix-pitfalls}
308
309- If upstream package.json does not have a "version" attribute, `node2nix` will crash. You will need to add it like shown in [the package.json section](#javascript-upstream-package-json).
310- `node2nix` has some [bugs](https://github.com/svanderburg/node2nix/issues/238) related to working with lock files from npm distributed with `nodejs_16`.
311- `node2nix` does not like missing packages from npm. If you see something like `Cannot resolve version: vue-loader-v16@undefined` then you might want to try another tool. The package might have been pulled off of npm.
312
313### yarn2nix {#javascript-yarn2nix}
314
315#### Preparation {#javascript-yarn2nix-preparation}
316
317You will need at least a `yarn.lock` file. If upstream does not have one you need to generate it and reference it in your package definition.
318
319If the downloaded files contain the `package.json` and `yarn.lock` files they can be used like this:
320
321```nix
322{
323 offlineCache = fetchYarnDeps {
324 yarnLock = src + "/yarn.lock";
325 hash = "....";
326 };
327}
328```
329
330#### mkYarnPackage {#javascript-yarn2nix-mkYarnPackage}
331
332`mkYarnPackage` will by default try to generate a binary. For package only generating static assets (Svelte, Vue, React, WebPack, ...), you will need to explicitly override the build step with your instructions.
333
334It's important to use the `--offline` flag. For example if you script is `"build": "something"` in `package.json` use:
335
336```nix
337{
338 buildPhase = ''
339 export HOME=$(mktemp -d)
340 yarn --offline build
341 '';
342}
343```
344
345The `distPhase` is packing the package's dependencies in a tarball using `yarn pack`. You can disable it using:
346
347```nix
348{
349 doDist = false;
350}
351```
352
353The configure phase can sometimes fail because it makes many assumptions which may not always apply. One common override is:
354
355```nix
356{
357 configurePhase = ''
358 ln -s $node_modules node_modules
359 '';
360}
361```
362
363or if you need a writeable node_modules directory:
364
365```nix
366{
367 configurePhase = ''
368 cp -r $node_modules node_modules
369 chmod +w node_modules
370 '';
371}
372```
373
374#### mkYarnModules {#javascript-yarn2nix-mkYarnModules}
375
376This will generate a derivation including the `node_modules` directory.
377If you have to build a derivation for an integrated web framework (rails, phoenix..), this is probably the easiest way.
378
379#### Overriding dependency behavior {#javascript-mkYarnPackage-overriding-dependencies}
380
381In the `mkYarnPackage` record the property `pkgConfig` can be used to override packages when you encounter problems building.
382
383For instance, say your package is throwing errors when trying to invoke node-sass:
384
385```
386ENOENT: no such file or directory, scandir '/build/source/node_modules/node-sass/vendor'
387```
388
389To fix this we will specify different versions of build inputs to use, as well as some post install steps to get the software built the way we want:
390
391```nix
392mkYarnPackage rec {
393 pkgConfig = {
394 node-sass = {
395 buildInputs = with final;[ python libsass pkg-config ];
396 postInstall = ''
397 LIBSASS_EXT=auto yarn --offline run build
398 rm build/config.gypi
399 '';
400 };
401 };
402}
403```
404
405#### Pitfalls {#javascript-yarn2nix-pitfalls}
406
407- If version is missing from upstream package.json, yarn will silently install nothing. In that case, you will need to override package.json as shown in the [package.json section](#javascript-upstream-package-json)
408- Having trouble with `node-gyp`? Try adding these lines to the `yarnPreBuild` steps:
409
410 ```nix
411 {
412 yarnPreBuild = ''
413 mkdir -p $HOME/.node-gyp/${nodejs.version}
414 echo 9 > $HOME/.node-gyp/${nodejs.version}/installVersion
415 ln -sfv ${nodejs}/include $HOME/.node-gyp/${nodejs.version}
416 export npm_config_nodedir=${nodejs}
417 '';
418 }
419 ```
420
421 - The `echo 9` steps comes from this answer: <https://stackoverflow.com/a/49139496>
422 - Exporting the headers in `npm_config_nodedir` comes from this issue: <https://github.com/nodejs/node-gyp/issues/1191#issuecomment-301243919>
423- `offlineCache` (described [above](#javascript-yarn2nix-preparation)) must be specified to avoid [Import From Derivation](#ssec-import-from-derivation) (IFD) when used inside Nixpkgs.
424
425## Outside Nixpkgs {#javascript-outside-nixpkgs}
426
427There are some other tools available, which are written in the Nix language.
428These that can't be used inside Nixpkgs because they require [Import From Derivation](#ssec-import-from-derivation), which is not allowed in Nixpkgs.
429
430If you are packaging something outside Nixpkgs, consider the following:
431
432### npmlock2nix {#javascript-npmlock2nix}
433
434[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.
435
436#### Pitfalls {#javascript-npmlock2nix-pitfalls}
437
438There are some [problems with npm v7](https://github.com/tweag/npmlock2nix/issues/45).
439
440### nix-npm-buildpackage {#javascript-nix-npm-buildpackage}
441
442[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.
443
444#### Pitfalls {#javascript-nix-npm-buildpackage-pitfalls}
445
446There are some [problems with npm v7](https://github.com/serokell/nix-npm-buildpackage/issues/33).