95 lines
4.1 KiB
Markdown
95 lines
4.1 KiB
Markdown
# Nix macOS Starter
|
|
|
|
A beginner-friendly Nix configuration for macOS using flakes, nix-darwin, Home Manager, and Mise.
|
|
|
|
## About
|
|
|
|
A clean, well-documented starting point for managing your macOS system declaratively with Nix. Includes sensible defaults for development tools, shell configuration, and system settings.
|
|
|
|
**Author:** Ben Gubler
|
|
|
|
## Prerequisites
|
|
|
|
1. **Install Nix** using the [Determinate Systems installer](https://docs.determinate.systems/#products) (download the graphical installer for macOS). After installation, restart your terminal.
|
|
|
|
**Note:** Homebrew is managed declaratively via nix-homebrew - if you already have it installed, it will auto-migrate. Otherwise, it's installed automatically.
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone and Configure
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/nebrelbug/nix-macos-starter ~/.config/nix
|
|
cd ~/.config/nix
|
|
```
|
|
|
|
### 2. Customize Your Configuration
|
|
|
|
**For Intel Mac Users:** Change the system architecture in `flake.nix` from `"aarch64-darwin"` to `"x86_64-darwin"` on line 28.
|
|
|
|
**Replace all placeholders:**
|
|
|
|
- `flake.nix`: `YOUR_USERNAME` (this sets the username for the entire system)
|
|
- `home/git.nix`: `YOUR_NAME`, `YOUR_EMAIL`
|
|
|
|
### 3. Apply the Configuration
|
|
|
|
```bash
|
|
# Build and switch to the configuration
|
|
darwin-rebuild switch --flake .#my-macbook
|
|
|
|
# Or use the alias after initial setup
|
|
nix-switch
|
|
```
|
|
|
|
## What's Included
|
|
|
|
**Development Tools**: [mise](https://mise.jdx.dev/) for Node.js/Python/Rust/etc., Zsh with Starship prompt, essential CLI tools (curl, vim, tmux, htop, tree, ripgrep, gh, zoxide), code quality tools (nil, biome, nixfmt-rfc-style)
|
|
|
|
**GUI Applications**: Cursor, Ghostty, VS Code, Zed, Raycast, CleanShot, HiddenBar, BetterDisplay, Discord, Slack, 1Password, Brave Browser, Obsidian, Spotify
|
|
|
|
**System Configuration**: Git setup, macOS optimizations (Finder, Touch ID sudo), Nix settings (flakes, garbage collection), declarative Homebrew management
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
nix-macos-starter/
|
|
├── flake.nix # Main flake configuration and inputs
|
|
├── darwin/
|
|
│ ├── default.nix # Core macOS system configuration
|
|
│ ├── settings.nix # macOS UI/UX preferences and defaults
|
|
│ └── homebrew.nix # GUI applications via Homebrew
|
|
├── home/
|
|
│ ├── default.nix # Home Manager configuration entry point
|
|
│ ├── packages.nix # Package declarations and mise setup
|
|
│ ├── git.nix # Git configuration
|
|
│ ├── shell.nix # Shell configuration
|
|
│ └── mise.nix # Development runtime management
|
|
└── hosts/
|
|
└── my-macbook/
|
|
├── configuration.nix # Host-specific packages and settings
|
|
└── shell-functions.sh # Custom shell scripts
|
|
```
|
|
|
|
## Customization
|
|
|
|
**Add CLI Tools**: Edit `home/packages.nix` packages array
|
|
**Add GUI Apps**: Edit `darwin/homebrew.nix` casks array
|
|
**Add Development Tools**: Add `${pkgs.mise}/bin/mise use --global tool@version` to `home/mise.nix` activation script
|
|
**Host-Specific Config**: Use `hosts/my-macbook/configuration.nix` for machine-specific packages/apps and `custom-scripts.sh` for shell scripts
|
|
|
|
## Troubleshooting
|
|
|
|
**"Command not found"**: Restart terminal
|
|
**Permission denied**: Use `sudo darwin-rebuild switch --flake .#my-macbook`
|
|
**Homebrew apps not installing**: nix-homebrew handles this automatically; ensure `/opt/homebrew/bin` in PATH
|
|
**Git config not applying**: Replace all `YOUR_*` placeholders, re-run darwin-rebuild
|
|
|
|
**Need help?** Check [Nix manual](https://nixos.org/manual/nix/stable/), [nix-darwin docs](https://github.com/LnL7/nix-darwin), [Home Manager options](https://nix-community.github.io/home-manager/options.html)
|
|
|
|
## Credits
|
|
|
|
- [Ethan Niser](https://github.com/ethanniser) for his [config repo](https://github.com/ethanniser/config) which I used as a reference for this project.
|
|
- David Haupt's excellent [tutorial series](https://davi.sh/blog/2024/01/nix-darwin/) which (although slightly outdated) helped me understand the basics of Nix.
|