fuwn.net
⛩️ Powerful yet Minimal Nix Dependency Manager
flake
flakes
home-manager
nixos
go
nix
dependency
dependencies
1# ⛩️ Yae
2
3Yae is a powerful yet minimal dependency manager intended for use with Nix,
4which functions similar to [niv](https://github.com/nmattia/niv/) and [`npins`](https://github.com/andir/npins/).
5
6<details closed>
7 <summary>Why should I consider Yae over niv or <code>npins</code>?</summary>
8
9 1. No unnecessary helper Nix expressions are needed by Yae.
10
11 niv and `npins` spit out medium-to-large sized Nix expressions that vary in
12 complexity in the form of a file that you need to keep in sync with their
13 mainline sources. This requires additional upgrade commands in the CLI and
14 more effort to maintain. A Yae environment is a single file and can be placed
15 anywhere and read just as simply.
16 2. Yae has a simple and coherent source tree. niv has a total of 10000 LOC
17 (lines of code), `npins` sits at almost 6000 LOC flat, and Yae stands at just
18 shy of 1500 LOC when looking at all files. Yae's core source code itself sits
19 at just 462 LOC, which is much, **much** smaller than that of niv and `npins`'
20 core trees. This is all to say that Yae implements everything needed to functionally
21 replace niv and `npins` in any workflow, and in much more efficient and concise
22 codebase.
23 3. Yae is simple by nature in design and usage philosophy.
24
25 niv and `npins` are great, but are far too ~~overkill~~ overengineered for me
26 and many other consumers. I say overengineered because I was able to write out
27 Yae's initial implementation in just about thirty-minutes to an hour, and it
28 was already complete enough for me to replace niv or `npins` in all of my production
29 workflows. If you need some niche feature that niv or `npins` has, use them,
30 but if not, Yae is here for you.
31
32</details>
33
34## Introduction
35
36You can try out Yae without installing anything permanently on your system by running
37`nix run github:Fuwn/yae`.
38
39Check out [Tsutsumi](https://github.com/Fuwn/tsutsumi) to see an example of Yae running
40in a production environment. Tsutsumi fully leverages the power of Yae to manage
41and automagically update the sources of the Nix packages it provides using a simple
42GitHub Actions CRON workflow.
43
44## Usage
45
46View the [installations instructions](#installation) below to set up Yae after
47running `yae init`.
48
49### Example Environment Setup
50
51```sh
52# Initialises a Yae environment in the current directory by creating an empty `yae.json`
53# file
54yae init
55
56# Adds a Yae dependency named `zen-browser-twilight-bin` using a floating tag
57# (tag always remain `twilight`, but may receive frequent hash changes)
58yae add \
59 --type binary \
60 --version twilight \
61 --unpack \
62 zen-browser-twilight-bin \
63 'https://github.com/zen-browser/desktop/releases/download/{version}/zen.linux-specific.tar.bz2'
64
65# Adds a Yae dependency named `zen-browser-bin` pinned at tag `1.0.1-a.7`
66yae add \
67 --type git \
68 --version 1.0.1-a.7 \
69 --unpack \
70 zen-browser-bin \
71 'https://github.com/zen-browser/desktop/releases/download/{version}/zen.linux-specific.tar.bz2'
72
73# Adds a Yae dependency named `yaak` pinned at tag `2024.10.1` with tag trimming
74# for updates
75yae add \
76 --type git \
77 --unpack=false \
78 --version 2024.10.1 \
79 --trim-tag-prefix v \
80 yaak \
81 'https://github.com/yaakapp/app/releases/download/v{version}/yaak_{version}_amd64.AppImage.tar.gz'
82
83# Updates all dependencies, e.g., updates the hash of `zen-browser-twilight-bin`
84# and bumps the version of `zen-browser-bin` to `1.0.1-a.8`, handling URL and
85# hash recalculations, etc.
86yae update
87
88# Only updates `zen-browser-twilight-bin`
89yae update zen-browser-twilight-bin
90```
91
92## Installation
93
94You can either install Yae through the flake that this repository exposes or
95through [Tsutsumi](https://github.com/Fuwn/tsutsumi).
96
97[Tsutsumi](https://github.com/Fuwn/tsutsumi) provides both flake and flake-less installation
98options, while this repository only provides installation support through flakes
99using the exported `inputs.yae.packages.${pkgs.system}.yae` package.
100
101<details closed>
102 <summary>Click here to see a minimal Nix flake that exposes a development shell with Yae bundled.</summary>
103
104```nix
105# Enter the development shell using `nix develop --impure` (impure is used here because `nixpkgs` internally
106# assigns `builtins.currentSystem` to `nixpkgs.system` for the sake of simplicity in this example)
107{
108 inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
109
110 inputs.tsutsumi = {
111 url = "github:Fuwn/tsutsumi";
112 inputs.nixpkgs.follows = "nixpkgs";
113 };
114
115 outputs = { nixpkgs, tsutsumi, self }:
116 let pkgs = import nixpkgs { inherit self; }; in {
117 devShells.${pkgs.system}.default = pkgs.mkShell {
118 buildInputs = [ tsutsumi.packages.${pkgs.system}.yae ];
119 };
120 };
121}
122```
123
124</details>
125
126### Integrating with Nix
127
128To add Yae support to your Nix expression after running `yae init`, just read
129from the Yae environment file. See the example below for more details.
130
131### Examples
132
133Check out the [`examples/`](./examples) directory for a couple of great examples
134of Yae managing different sources including Nixpkgs!
135
136#### Real-world Example
137
138Here's an example snippet taken from Tsutsumi's [`zen-browser-bin` package](https://github.com/Fuwn/tsutsumi/blob/main/pkgs/zen-browser-bin.nix)
139and [`yae.json`](https://github.com/Fuwn/tsutsumi/blob/main/yae.json#L59-L67)
140showcasing Yae in action.
141
142<details closed>
143 <summary>Expand this!</summary>
144
145```nix
146# pkgs/zen-browser-bin.nix
147
148# This expression produces the `zen-browser-bin` package that Tsutsumi exposes
149# as a Nix package derivation.
150#
151# Since it is managed by Yae, it is kept 100% up to date with zero effort through
152# a Github Actions CRON job workflow that executes `yae update` periodically.
153{
154 pkgs,
155 self,
156 # This line imports Yae's environment configuration to be used below.
157 yae ? builtins.fromJSON (builtins.readFile "${self}/yae.json"),
158}:
159# Tsutsumi exposes two versions of the Zen browser, the latest stable release
160# and the latest Twilight release (a bleeding edge, daily build). This library
161# function is one that takes one of two Yae sources for the Zen browser, and produces
162# a Nix package derivation for it.
163import "${self}/lib/zen-browser-bin.nix" {
164 # Here, the latest SHA256 hash and release version from Yae are passed to Tsutsumi's
165 # Zen browser package function.
166 #
167 # If `yae update` is ran and a new release is detected, these values are
168 # updated by Yae, which then triggers another workflow to build and send the
169 # resulting derivation to Tsutsumi's binary cache.
170 inherit (yae.zen-browser-bin) sha256 version;
171
172 # To generate the Twilight release package, this is all that is changed.
173 # inherit (yae.zen-browser-twilight-bin) sha256 version;
174} { inherit pkgs; }
175```
176
177</details>
178
179## `--help`
180
181```text
182NAME:
183 yae - Nix Dependency Manager
184
185USAGE:
186 yae [global options] command [command options]
187
188DESCRIPTION:
189 Nix Dependency Manager
190
191AUTHOR:
192 Fuwn <contact@fuwn.me>
193
194COMMANDS:
195 init Initialise a new Yae environment
196 add Add a source
197 drop Drop a source
198 update Update one or all sources
199 help, h Shows a list of commands or help for one command
200
201GLOBAL OPTIONS:
202 --sources value Sources path (default: "./yae.json")
203 --debug Enable debug output (default: false)
204 --silent Silence log output (default: false)
205 --dry-run Prevents writing to disk (default: false)
206 --help, -h show help
207
208COPYRIGHT:
209 Copyright (c) 2024-2025 Fuwn
210```
211
212## Licence
213
214Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
215[MIT license](LICENSE-MIT) at your option.
216
217Unless you explicitly state otherwise, any contribution intentionally submitted
218for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
219be dual licensed as above, without any additional terms or conditions.