hmemcpy / hmemcpy/toolkata

Tutorial: Nix for Homebrew users (nix-brew pairing)

Open
#4 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
2
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Summary

Add a new tutorial pairing: **Learn Nix if you know Homebrew**.

## Motivation

Homebrew users are familiar with imperative package management (`brew install`, `brew uninstall`). Nix offers a paradigm shift to functional, declarative, reproducible package management — similar to how jj-git teaches a new VCS model to git users.

**Why this works:**
- Familiar starting point (brew commands)
- Mind-bending paradigm shift (functional package management)
- Immediate practical benefit (reproducible dev envs, rollbacks)
- Fits the "X if you know Y" format

## Proposed Structure (~10 steps, ~35 min)

| Step | Concept | Brew → Nix |
|------|---------|------------|
| 1 | Install Nix | Determinate Nix installer |
| 2 | First ephemeral shell | `nix-shell -p cowsay` vs `brew install` |
| 3 | Package search | Finding attributes in nixpkgs |
| 4 | Development environment | `nix-shell -p git nodejs rustup` |
| 5 | The "works on my machine" problem | Why ephemeral isn't enough |
| 6 | Declarative shell.nix | Reproducible dev envs committed to git |
| 7 | Home Manager intro | Replacing `brew install` for permanent packages |
| 8 | Multi-version management | `nix-shell -p nodejs_18` vs `nodejs_20` |
| 9 | Rollbacks | `nix-env --rollback` (something brew can't do) |
| 10 | Flakes intro (optional) | The modern Nix way |

## Key Comparison Points

| Brew workflow | Nix equivalent | Concept taught |
|--------------|----------------|----------------|
| `brew install node` | `nix-shell -p nodejs` | Ephemeral environments |
| `brew install` (permanent) | `home-manager` or `nix profile` | Declarative package management |
| `brew uninstall` | Packages garbage-collected when unused | Immutable store |
| `brew switch node@18` | `nix-shell -p nodejs_18` | Multiple versions coexist |
| `Brewfile` | `shell.nix` / `flake.nix` | Reproducible environments |
| `brew services start` | `services.*.enable = true` | System configuration as code |

## Pedagogical Notes

**The "aha" moment:** Running `nix-shell -p python39` doesn't install Python permanently. Exit the shell, it's gone. No pollution, no version conflicts.

**The trap to avoid:** `nix-env -iA` (imperative install) looks like brew but breaks the Nix model. Tutorial must steer users toward declarative patterns early. See https://stop-using-nix-env.privatevoid.net/

**Prerequisites:** None beyond "uses Homebrew currently"

## Resources

- https://nixos.org/guides/how-nix-works/
- https://zero-to-nix.com/
- https://nix.dev/tutorials/first-steps/ad-hoc-shell-environments
- https://stop-using-nix-env.privatevoid.net/

## Category

`Package Management`

## Related

- Pairings format reference: `toolkata-content/pairings.ts`
- Similar paradigm-shift tutorial: `jj-git`

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.