docs(readme): improve Nix development environment setup instructions #94
Conversation
- Add Nix installation command using experimental installer - Add instructions for enabling flakes if not already enabled - Clarify direnv activation (use existing .envrc) - Link to flake.nix for reference - Reorganise useful commands into separate section
ryoppippi
force-pushed
the
docs/nix-setup-instructions
branch
from
ccc0ece to
05ddd3f
Compare
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
This PR improves the Nix development environment setup documentation by restructuring it into clear, sequential sections with explicit installation and activation steps.
- Adds explicit Nix installation instructions using the experimental installer
- Reorganizes content into logical subsections: Installation, Activation, and Useful Commands
- Clarifies direnv usage and adds reference to flake.nix
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| nix flake check | ||
| ```bash | ||
| # Automatic activation with direnv (recommended) | ||
| direnv allow |
There was a problem hiding this comment.
The comment says "use existing .envrc" in the PR description, but the documentation doesn't clarify that an .envrc file already exists in the repository. Users unfamiliar with direnv might not understand what they're allowing. Consider adding a brief note that this activates the existing .envrc configuration in the repository.
| curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \ | ||
| sh -s -- install |
There was a problem hiding this comment.
The experimental installer URL may not be the most appropriate choice for documentation aimed at general users. The experimental installer is intended for testing new features and may have stability issues. Consider using the official stable installer instead: sh <(curl -L https://nixos.org/nix/install) --daemon or directing users to the official installation page at https://nixos.org/download.html for platform-specific instructions.
| ```bash | ||
| # Enter development environment (auto-installs dependencies and git hooks) | ||
| nix develop | ||
| # Install Nix with flakes enabled (if not already installed) |
There was a problem hiding this comment.
The conditional check "if not already installed" in the comment contradicts the instruction itself. The experimental installer command shown will attempt to install Nix unconditionally and will fail if Nix is already installed. Consider either removing the parenthetical "(if not already installed)" or adding instructions for users to check if Nix is already installed first.
| # Install Nix with flakes enabled (if not already installed) | |
| # Install Nix with flakes enabled |
| # If flakes are not enabled, enable them with: | ||
| mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf |
There was a problem hiding this comment.
The instruction to enable flakes by appending to nix.conf could result in duplicate entries if run multiple times. Consider using a command that checks for existing configuration or overwrites safely, or add a note to users that they should only run this once or check if flakes are already enabled first.
| # If flakes are not enabled, enable them with: | |
| mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf | |
| # If flakes are not enabled, enable them (idempotent): | |
| mkdir -p ~/.config/nix | |
| if ! grep -q "experimental-features .*flakes" ~/.config/nix/nix.conf 2>/dev/null; then | |
| echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf | |
| fi |
Summary
Test plan
Summary by cubic
Streamlined the README’s Nix setup to make onboarding faster and the dev environment easier to activate. Added an install command (experimental installer), steps to enable flakes, clarified direnv activation, linked to flake.nix, and grouped useful commands.
Written for commit 05ddd3f. Summary will update on new commits.