Amp-Thread-ID: https://ampcode.com/threads/T-a6cf4bd2-36d0-4ef8-ada6-a8e2850fcacf Co-authored-by: Amp <amp@ampcode.com>
3.4 KiB
NixOS Development Setup
This project includes a flake.nix for reproducible development on NixOS and other Nix-based systems.
Quick Start
-
Enter the development shell:
nix develop -
First-time setup:
npm install npm run rebuild # Rebuild native modules for Electron -
Build and run:
npm run dev
What's Included
The Nix development environment provides:
- Node.js 20 - JavaScript runtime
- Electron 38 - Desktop application framework (from nixpkgs, not npm)
- Build tools: git, python3 (with setuptools), pkg-config, gcc, make
- Electron dependencies: All required system libraries (X11, GTK3, Mesa, etc.)
- Proper library paths: Automatically configured
LD_LIBRARY_PATH
Why Use Nix?
- Reproducible: Same versions of tools across all machines
- Isolated: No conflicts with system packages
- Complete: All dependencies included, nothing to install manually
- NixOS-friendly: Electron binaries work out of the box
Important Notes
System Electron vs npm Electron
This setup uses the Electron binary from nixpkgs instead of the npm package. This is necessary on NixOS because:
- npm Electron binaries are dynamically linked for generic Linux
- NixOS has a unique library structure that requires patching
- nixpkgs provides pre-patched, working Electron binaries
The environment variable ELECTRON_OVERRIDE_DIST_PATH tells npm scripts to use the system Electron.
Native Modules
After npm install, you must run npm run rebuild to rebuild native modules (like node-pty) for the Electron version:
npm run rebuild # or: npx electron-rebuild
This ensures native modules are compiled against Electron's Node.js version, not your system Node.js.
Available Commands
# Setup
npm install # Install npm dependencies
npm run rebuild # Rebuild native modules for Electron
# Development
npm run build # Build TypeScript and Tailwind CSS
npm run dev # Build and run Electron app
electron . # Run the already-built app
# Production
npm run pack # Package for distribution (directory)
npm run dist # Build distributable packages
Troubleshooting
"Cannot find module" errors for native modules
Run npm run rebuild to recompile native modules for Electron.
"Missing X server or $DISPLAY" error
This is normal if you're running from SSH or a headless environment. The app needs a display server (X11 or Wayland). If you see this briefly when running locally with a display, it's just the app starting up.
Library path issues
The flake automatically sets LD_LIBRARY_PATH for all required libraries. If you encounter missing library errors, check that you're inside the nix develop shell.
Directory Layout
FleetCode/
├── flake.nix # Nix flake configuration
├── flake.lock # Locked dependency versions
├── package.json # npm dependencies and scripts
├── main.ts # Electron main process
├── renderer.ts # Electron renderer process
├── dist/ # Compiled output (generated)
└── node_modules/ # npm dependencies (generated)
Updating Dependencies
Nix dependencies
nix flake update
npm dependencies
npm update
npm run rebuild # Don't forget to rebuild!