A simple helper that makes it easy to package Nu scripts with Nix, including inline dependency declarations for external commands and other packaged scripts.
flake
nu
nushell
nix
even more readme changes
+18
-9
+18
-9
README.md
+18
-9
README.md
···
5
5
6
6
## Why nu2nix?
7
7
8
-
Nu scripts are great for small utilities and automation tasks, but packaging them with Nix means maintaining a separate Nix expression that actually builds your script into a runnable Nix package. Your dependency information ends up living in that Nix expression instead of with your script. This also ends up making it more difficult to, say, package a directory of scripts using `builtins.readDir` and some mapping magic, which is the original use case I created nu2nix for.
8
+
Nu scripts are great for small utilities and automation tasks, but packaging them with Nix means maintaining a separate Nix expression that actually builds your script into a runnable Nix package. Your dependency information ends up living in that Nix expression instead of with your script. This also makes it harder to package collections of scripts programmatically, such as using `builtins.readDir` and mapping over the result. That was the original use case that motivated nu2nix.
9
9
10
-
nu2nix fixes these problems by keeping your dependency information stored inside your Nu scripts themselves. Just point nu2nix at a script file and give it a package set. It'll scan your script for an `External Dependencies` block comment and parse it, then the resulting package will have all of the dependencies you declared in your block comment in `$PATH`. nixpkgs (`pkgs`), flake inputs (`inputs`), and a flake's `self` argument are all supported as dependency sources.
10
+
nu2nix fixes these problems by keeping your dependency information stored inside your Nu scripts themselves. Just point nu2nix at a script file and give it a package scope. It'll scan your script for an `External Dependencies` block comment and parse it, then the resulting package will have all of the dependencies you declared in your block comment in `$PATH`. nixpkgs (`pkgs`), flake inputs (`inputs`), and a flake's `self` argument are all supported as dependency sources.
11
11
12
12
## Try it Out
13
13
···
49
49
50
50
## External Dependencies
51
51
52
-
nu2nix supports a custom format for declaring external dependencies inline in your script files.
52
+
nu2nix supports a custom format for declaring external dependencies inline in your script files, using an `External Dependencies` block comment.
53
+
54
+
The `External Dependencies` block comment must:
55
+
56
+
- start with `START: External Dependencies`.
57
+
- end with `END: External Dependencies`.
58
+
- contain no more than one (1) dependency per line.
59
+
53
60
All declared dependencies are automatically added to the script's `$PATH` when executed, using a wrapper script.
54
61
55
62
```nu
···
67
74
```
68
75
69
76
> [!WARNING]
70
-
> Only dependencies you declare in the `External Dependencies` comment or the `extraDependencies` argument to `mkNuScript` will be included in the script's `$PATH` wrapper. `$PATH` is completely overridden, not appended to. This helps with reproducibility; if an external command isn't explicitly included in the wrapper, Nushell won't be able to find it at runtime. The only exception to this is Nushell itself, as Nushell is implicitly added to the script's `$PATH` wrapper by `mkNuScript`.
77
+
> Only dependencies declared in the `External Dependencies` block comment or passed through `mkNuScript`'s `extraDependencies` argument are available at runtime.
78
+
> nu2nix replaces `$PATH` entirely instead of extending it. This makes scripts reproducible; if a command is not explicitly declared, it will not be available.
79
+
> Nushell itself is the exception, as it's automatically added by `mkNuScript`.
71
80
72
81
### Dependency Formats
73
82
74
-
| Scope | Usage Example | Resolves to | `mkNuScript` Argument |
75
-
| :---------------: | :----------------------: | :-----------------------------------------: | :-----------------------------------------------: |
76
-
| _`<unqualified>`_ | `git` | `pkgs.git` | `pkgs` (raises error when missing) |
77
-
| `inputs` | `inputs.vicinae.default` | `inputs.vicinae.packages.${system}.default` | `inputs` (raises error when missing & referenced) |
78
-
| `self` | `self.helper-script` | `self.packages.${system}.helper-script` | `self` (raises error when missing & referenced) |
83
+
| Scope | Usage Example | Resolves to | `mkNuScript` Argument |
84
+
| :--------------: | :----------------------: | :-----------------------------------------: | :-----------------------------------------------: |
85
+
| Default (`pkgs`) | `git` | `pkgs.git` | `pkgs` (raises error when missing) |
86
+
| `inputs` | `inputs.vicinae.default` | `inputs.vicinae.packages.${system}.default` | `inputs` (raises error when missing & referenced) |
87
+
| `self` | `self.helper-script` | `self.packages.${system}.helper-script` | `self` (raises error when missing & referenced) |