Skip to content

docs(readme): improve Nix development environment setup instructions #94

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ryoppippi merged 1 commit into from
Jan 5, 2026
Merged

docs(readme): improve Nix development environment setup instructions #94

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,20 +337,27 @@ For more examples, check out the [examples/](examples/) directory:

### Using Nix (Recommended)

[Nix](https://nixos.org/) with flakes provides a consistent development environment:
This project includes a Nix flake for reproducible development environments. All development tools are defined in [flake.nix](./flake.nix) and provided via Nix.

#### Installing Nix

```bash
# Enter development environment (auto-installs dependencies and git hooks)
nix develop
# Install Nix with flakes enabled (if not already installed)
Copy link

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
# Install Nix with flakes enabled (if not already installed)
# Install Nix with flakes enabled

Copilot uses AI. Check for mistakes.
curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
sh -s -- install
Comment on lines +346 to +347
Copy link

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

# Or with direnv (recommended for automatic activation)
direnv allow
# If flakes are not enabled, enable them with:
mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
Comment on lines +349 to +350
Copy link

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
# 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

Copilot uses AI. Check for mistakes.
```

# Format code
nix fmt
#### Activating the Development Environment

# Run checks
nix flake check
```bash
# Automatic activation with direnv (recommended)
direnv allow
Copy link

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot uses AI. Check for mistakes.

# Or manual activation
nix develop
```

The Nix development environment includes:
Expand Down