{"id":13799108,"url":"https://github.com/nix-community/napalm","last_synced_at":"2026-02-11T13:34:17.510Z","repository":{"id":37656149,"uuid":"182396658","full_name":"nix-community/napalm","owner":"nix-community","description":"Support for building npm packages in Nix and lightweight npm registry [maintainer=?]","archived":false,"fork":false,"pushed_at":"2024-06-09T10:37:55.000Z","size":165,"stargazers_count":118,"open_issues_count":19,"forks_count":18,"subscribers_count":7,"default_branch":"master","last_synced_at":"2026-01-29T10:15:20.087Z","etag":null,"topics":["build","hacktoberfest","javascript","nix","npm"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nix-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"nix-community"}},"created_at":"2019-04-20T11:19:05.000Z","updated_at":"2026-01-08T01:31:32.000Z","dependencies_parsed_at":"2023-12-20T20:24:01.977Z","dependency_job_id":"b17364f1-5a4d-4b29-ab4e-a73c49db03b6","html_url":"https://github.com/nix-community/napalm","commit_stats":{"total_commits":121,"total_committers":16,"mean_commits":7.5625,"dds":0.6859504132231404,"last_synced_commit":"e1babff744cd278b56abe8478008b4a9e23036cf"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nix-community/napalm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnapalm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnapalm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnapalm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnapalm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nix-community","download_url":"https://codeload.github.com/nix-community/napalm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnapalm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29333565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T12:42:24.625Z","status":"ssl_error","status_checked_at":"2026-02-11T12:41:23.344Z","response_time":97,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["build","hacktoberfest","javascript","nix","npm"],"created_at":"2024-08-04T00:00:58.916Z","updated_at":"2026-02-11T13:34:17.488Z","avatar_url":"https://github.com/nix-community.png","language":"Nix","funding_links":["https://opencollective.com/nix-community"],"categories":["Nix","Programming Languages"],"sub_categories":["Node.js"],"readme":"# Napalm\n\n**This project is looking for a new maintainer, [see](https://github.com/nix-community/napalm/issues/67)**\n\n\u003e When faced with a JavaScript codebase, napalm is just what you need.\n\u003e\n\u003e -- anonymous\n\n## Table of contents\n\n* [Building npm packages in Nix with Napalm](#building-npm-packages-in-nix-with-napalm)\n  * [Basic Napalm usage](#basic-napalm-usage)\n  * [Napalm with Nix flakes](#napalm-with-nix-flakes)\n* [More complicated scenarios with Napalm](#handling-complicated-scenarios-with-napalm)\n  * [Custom node.js version](#custom-nodejs-version)\n  * [Pre/Post Npm hooks](#prepost-npm-hooks)\n  * [Multiple package locks](#multiple-package-locks)\n  * [Patching Npm packages](#patching-npm-packages-before-fetching-them-with-npm)\n  * [Customizing patching mechanism of npm packages](#customizing-patching-mechanism-of-npm-packages)\n* [How does it work ?](#how-does-napalm-work-)\n* [Napalm - a lightweight npm registry](#napalm---a-lightweight-npm-registry)\n\n## Building npm packages in Nix with Napalm\n\n### Basic Napalm usage\n\nUse the `buildPackage` function provided in the [`default.nix`](./default.nix)\nfor building npm packages (replace `\u003cnapalm\u003e` with the path to napalm;\nwith [niv]: `niv add nmattia/napalm`):\n\n``` nix\nlet\n    napalm = pkgs.callPackage \u003cnapalm\u003e {};\nin napalm.buildPackage ./. {}\n```\n\nAll executables provided by the npm package will be available in the\nderivation's `bin` directory.\n\n**NOTE**: napalm uses the package's `package-lock.json` (or\n`npm-shrinkwrap.json`) for building a package database. Make sure there is\neither a `package-lock.json` or `npm-shrinkwrap.json` in the source.\nAlternatively provide the path to the package-lock file:\n\n``` nix\nlet\n    napalm = pkgs.callPackage \u003cnapalm\u003e {};\nin napalm.buildPackage ./. { packageLock = \u003cpath/to/package-lock\u003e; }\n```\n\n### Napalm with Nix flakes\n\nIf you want to use Napalm in your flake project, you can do that by adding it to your inputs and either passing `napalm.overlays.default` to your Nixpkgs instance, or by using the `napalm.legacyPackages` `buildPackage` output. To configure the latter's environment, be sure to look at [the complicated scenarios](#handling-complicated-scenarios-with-napalm) and potentially set the `nixpkgs` input of napalm with `follows`.\n\n#### Example `flake.nix`\n\n```nix\n{\n  inputs.nixpkgs.url = \"github:NixOS/nixpkgs/nixpkgs-unstable\";\n  inputs.napalm.url = \"github:nix-community/napalm\";\n\n  # NOTE: This is optional, but is how to configure napalm's env\n  inputs.napalm.inputs.nixpkgs.follows = \"nixpkgs\";\n\n  outputs = { self, nixpkgs, napalm }: \n  let\n    system = \"x86_64-linux\";\n    pkgs = nixpkgs.legacyPackages.\"${system}\";\n  in {\n    # Assuming the flake is in the same directory as package-lock.json\n    packages.\"${system}\".package-name = napalm.legacyPackages.\"${system}\".buildPackage ./. { };\n\n    devShells.\"${system}\".shell-name = pkgs.mkShell {\n      nativeBuildInputs = with pkgs; [ nodejs ];\n    };\n  };\n}\n```\n\n#### Flake Template\n\nThere is also a template that can help you use napalm in your project. You can use it in a new, empty directory by running:\n\n```shell\nnix flake init -t \"github:nix-community/napalm\"\n```\n\n## Handling complicated scenarios with Napalm\n\nExamples below assume that you have imported `napalm` in some way.\n\n### Custom node.js version\n\nNapalm makes it quite simple to use custom node.js (with npm) version.\nThis is controlled via `nodejs` argument.\n\n#### Example 1\n\nChanging node.js version to the one that is supplied in `nixpkgs`:\n\n```nix\n{ napalm, nodejs-16_x, ... }:\nnapalm.buildPackage ./. {\n\tnodejs = nodejs-16_x;\n}\n```\n\n#### Example 2\n\nChanging node.js version to some custom version (just an idea):\n\n```nix\n{ napalm, nodejs-12_x, ... }:\nlet\n\tnodejs = nodejs-12_x.overrideAttrs (old: rec {\n\t\tpname = \"nodejs\";\n\t\tversion = \"12.19.0\";\n\t\tsha256 = \"1qainpkakkl3xip9xz2wbs74g95gvc6125cc05z6vyckqi2iqrrv\";\n\t\tname = \"${pname}-${version}\";\n\n\t\tsrc = builtins.fetchurl {\n\t\t\turl =\n\t\t\t\"https://nodejs.org/dist/v${version}/node-v${version}.tar.xz\";\n\t\t\tinherit sha256;\n\t\t};\n\t});\nin\nnapalm.buildPackage ./. {\n\tinherit nodejs;\n}\n```\n\n### Pre/Post Npm hooks\n\nNapalm allows to specify commands that are run before and after every `npm` call.\nThese hooks work also for nested `npm` calls thanks to npm override mechanism.\n\n#### Example\n\nPatching some folder with executable scripts containing shebangs (that may be generated by npm script):\n\n```nix\n{ napalm, ... }:\nnapalm.buildPackage ./. {\n\tpostNpmHook = ''\n\tpatchShebangs tools\n\t'';\n}\n```\n\n### Multiple package locks\n\nNapalms allows to specify multiple package locks.\nThis may be useful for some project which consist of some smaller projects.\n\n#### Example\n\n```nix\n{ napalm, ... }:\nnapalm.buildPackage ./. {\n\t# package-lock.json that is in the root of the project\n\t# is not required to be specified in `additionalpackagelocks`\n\t# If you want to specify it, you can use `packageLock` argument.\n\tadditionalPackageLocks = [\n\t./frontend/package-lock.json\n\t./tests/package-lock.json\n\t];\n}\n```\n\n### Patching npm packages (before fetching them with npm)\n\n*This is very useful for errors like: `Invalid interpreter`*\n\nNapalm has an ability to patch fetched npm packages before serving them to the npm.\nBy default patching fixes shebangs and binaries that are localized and the tarballs.\nNapalm also updates `package-lock.json` with new `integrity` hashes.\n\n#### Example\n\nTo enable patching, just use:\n\n```nix\n{ napalm, ... }:\nnapalm.buildPackage ./. {\n\tpatchPackages = true;\n}\n```\n\nThis will force repacking of all dependencies, though, so you might want to patch only specific dependencies by passing an empty attribute set to the next method.\n\n### Customizing patching mechanism of npm packages\n\nSometimes it is required to manually patch some package.\nNapalm allows that via `customPatchPackages` attribute.\nThis attribute is a set of that overrides for packages that will be patched.\n\n#### Example\n\n```nix\n{ napalm, ... }:\nnapalm.buildPackage ./. {\n\t# Arguments that are passed to the overrider:\n\t# `pkgs` - Nixpkgs used by Napalm\n\t# `prev` - Current set that will be passed to mkDerivation\n\tcustomPatchPackages = {\n\t\t\"react-native\" = {\n\t\t\t\"0.65.0\" = pkgs: prev: {\n\t\t\t\tEXAMPLE_ENV_VAR = \"XYZ\";\n\t\t\t\tdontBuild = false;\n\t\t\t\tbuildPhase = ''\n\t\t\t\t# You can copy some stuff here or run some custom stuff\n\t\t\t\t'';\n\t\t\t};\n\t\t};\n\n\t\t# Version is not required. When it is not specified it\n\t\t# applies override to all packages with that name.\n\t\t\"node-gyp-builder\" = pkgs: prev: { };\n\t};\n}\n```\n\n## How does Napalm work ?\n\nThese are general steps that Napalm makes when building packages (if you want to learn more, see source code of `default.nix`):\n\n1. Napalm loads all `package-lock.json` files and parses them. Then it fetches all specified packages into the Nix Store.\n2. (optional) Napalm patches npm packages and stores their output in new location. Then uses this location as default package location in Nix Store.\n3. Napalm creates snapshot that consists of packages names, version and paths to locations in Nix Store that contain them.\n4. (optional) Napalm patches `package-lock.json` integrity if the packages were patched, so that they will work with `npm install`.\n5. Napalm sets up `napalm-registry` which as a main argument accepts snapshot of npm packages and them serves them as if it was npm registry server.\n6. Napalm sets up npm so that it thinks `napalm-registry` server is default npm registry server.\n7. Napalm overrides npm which allows using custom npm hooks (every time it is called) as well as some other default patching activities.\n8. Napalm calls all the npm commands.\n9. Napalm installs everything automatically or based on what was specified in `installPhase`.\n\n## Napalm - a lightweight npm registry\n\nUnder the hood napalm uses its own package registry. The registry is available\nin [default.nix](./default.nix) as `napalm-registry`.\n\n```\nUsage: napalm-registry [-v|--verbose] [--endpoint ARG] [--port ARG] --snapshot ARG\n\nAvailable options:\n  -v,--verbose             Print information about requests\n  --endpoint ARG           The endpoint of this server, used in the Tarball URL\n  --port ARG               The to serve on, also used in the Tarball URL\n  --snapshot ARG           Path to the snapshot file. The snapshot is a JSON\n                           file. The top-level keys are the package names. The\n                           top-level values are objects mapping from version to\n                           the path of the package tarball. Example: { \"lodash\":\n                           { \"1.0.0\": \"/path/to/lodash-1.0.0.tgz\" } }\n  -h,--help                Show this help text\n```\n\n[niv]: https://github.com/nmattia/niv\n\n\n## Similar projects\n\n- [npmlock2nix](https://github.com/tweag/npmlock2nix)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnapalm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnix-community%2Fnapalm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnapalm/lists"}