Skip to content

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

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 #279

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
20 changes: 17 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -600,13 +600,27 @@ The tool description includes clear instructions for AI agents to always ask for

### Using Nix Flake

This project includes a Nix flake for reproducible development environments. If you have Nix installed with flakes enabled, you can use it to set up your 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 shell
nix develop
# Install Nix with flakes enabled (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
sh -s -- install
Comment on lines +609 to +610
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 official or recommended way to install Nix. The official Nix installation instructions at nixos.org recommend using curl -L https://nixos.org/nix/install | sh or the Determinate Systems installer. The artifacts.nixos.org/experimental-installer endpoint is for testing experimental features and may not be stable or officially supported. Consider using the official installer or documenting why the experimental version is needed.

Copilot uses AI. Check for mistakes.

Comment on lines +609 to +611
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.

Security consideration: piping a curl command directly to sh can be risky as it executes remote code without inspection. While this is a common pattern for installers, consider adding a note suggesting users review the installation script first, or provide an alternative two-step approach where users download the script first and then execute it after inspection.

Suggested change
curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | \
sh -s -- install
# Download the official Nix installer script
curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer -o nix-installer.sh
chmod +x nix-installer.sh
# (Recommended) Review the installer script before running it:
# $EDITOR nix-installer.sh
# Run the installer
./nix-installer.sh install

Copilot uses AI. Check for mistakes.
# 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 +612 to +614
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 instructions suggest enabling flakes after installing Nix, but the experimental installer (line 609-610) already enables flakes by default. This creates confusion - if the experimental installer is used, the flakes configuration step on line 613 is redundant. Either remove the experimental installer command and use the official installer, or clarify that line 613 is only needed if using a different installation method.

Copilot uses AI. Check for mistakes.

#### Activating the Development Environment

```bash
# Automatic activation with direnv (recommended)
direnv allow

# Or manual activation
Comment on lines +618 to +622
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 instructions don't mention that direnv itself needs to be installed before running direnv allow. Users who don't have direnv installed will encounter an error when trying to run this command. Consider adding a note about installing direnv first (e.g., through their package manager or the direnv installation guide), or mention that direnv is optional and they can skip directly to nix develop if they don't have it.

Suggested change
```bash
# Automatic activation with direnv (recommended)
direnv allow
# Or manual activation
You can activate the development environment either automatically using [`direnv`](https://direnv.net/) (optional) or manually with `nix develop`. If you want automatic activation, make sure `direnv` is installed on your system (for example via your package manager) before running the command below.
```bash
# Automatic activation with direnv (recommended, requires direnv to be installed)
direnv allow
# Or manual activation (no direnv required)

Copilot uses AI. Check for mistakes.
nix develop
```

The flake provides all necessary development dependencies including Node.js, pnpm, and other build tools.
Loading