NotAShelf/nix-evaluator-stats
1
0
Fork 0
mirror of https://github.com/NotAShelf/nix-evaluator-stats.git synced 2026-04-12 06:17:43 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: update usage section in README

Browse source 
Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I2d0fea6a39252d2c80a2693d54d476d96a6a6964
This commit is contained in:
raf 2026-01-23 00:20:04 +03:00
commit efdd9fcc99
Signed by: NotAShelf
GPG key ID: 29D95B64378DB4BF
1 changed files with 47 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

55
docs/README.md
View file

@ -1,11 +1,30 @@
# nix-evaluator-stats
A pretty visualiser for Nix evaluator stats from `NIX_SHOW_STATS` and
`NIX_COUNT_CALLS` invocations.
<!-- markdownlint-disable MD033 -->
<div align="center">
<a alt="CI Status" href="https://github.com/NotAShelf/nix-evaluator-stats">
<img
src="https://github.com/NotAShelf/nix-evaluator-stats/actions/workflows/check.yml/badge.svg"
alt="Lints & Formatting"
/>
</a>
<a alt="Build & Deploy" href="https://notashelf.github.io/nix-evaluator-stats/">
<img
src="https://github.com/NotAShelf/nix-evaluator-stats/actions/workflows/deploy.yml/badge.svg"
alt="License"
/>
</a>
</div>
<!-- markdownlint-enable MD033 -->
![Demo](./assets/ns-demo.png)
ns takes the resulting JSON data from your Nix invocation with the relevant
`nix-evaluator-stats`, or "ns" for short, is a pretty visualiser for the Nix
evaluator stats export from `NIX_SHOW_STATS` and `NIX_COUNT_CALLS` invocations.
It takes the resulting JSON data from your Nix invocation with the relevant
variables, and provides a ✨ pretty ✨ dashboard-like visual with the ability to
compare your "snapshots" of benchmarks. Besides looking nice, it is helpful in
collecting statistics about your Nix commands and tracking performance
@ -16,13 +35,31 @@ regressions in subsequent exports.
Usage instructions are provided in the initial page. Simply navigate to the site
and provide the JSON export (or a file) to render the statistics. The number of
rendered fields might differ based on your Nix version or implementation (Lix,
Snix, etc.) Please crate an issue if the render looks wrong or incorrect.
Snix, etc.) The classic usage looks like this:
```bash
# Invoke a Nix command with NIX_SHOW_STATS=1
$ NIX_SHOW_STATS=1 nix eval nixpkgs#hello -- --option eval-cache false # disable eval-cache for accuracy
```
1. Create the JSON export
2. Copy it
3. Paste it in the input field that appears the first time you visit the site
Once you hit "Load", the JSON will be parsed and you'll be looking at a dash
board of your export. By using the snapshot feature, i.e., saving a particular
analysis you may compare two _named_ analyses at a time.
> [!NOTE]
> `nix-evaluator-stats` was created in a very short duration, and there might be
> UI bugs or areas where UI polish is very clearly missing. Please crate an
> issue if the generated graph or the site UI looks off. Thanks :)
## Hacking
`nix-evaluator-stats` (or "ns" for short) is built with Vite, using
Typescript-React (`.tsx`) and SolidJS. A Nix shell is provided, and NPM
dependencies can be fetched with `pnpm` while inside the dev shell.
This project is built with Vite, using Typescript-React (`.tsx`) and SolidJS. A
Nix shell is provided, and dependencies can be fetched with `pnpm` while inside
the dev shell.
```bash
# Run the live server
@ -33,7 +70,9 @@ $ pnpm run build
```
If submitting pull requests, please ensure that format (`pnpm run fmt`) and lint
(`pnpm run lint`) tasks are ran beforehand.
(`pnpm run lint`) tasks are ran beforehand. The automated CI will tell you
whether your code matches the requirements, but it's a good rule of thumb to do
this before submitting your PR.
## License