# NixOS Development Setup This project includes a `flake.nix` for reproducible development on NixOS and other Nix-based systems. ## Quick Start 1. **Enter the development shell:** ```bash nix develop ``` 2. **First-time setup:** ```bash npm install npm run rebuild # Rebuild native modules for Electron ``` 3. **Build and run:** ```bash 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: 1. npm Electron binaries are dynamically linked for generic Linux 2. NixOS has a unique library structure that requires patching 3. 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: ```bash 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 ```bash # 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 ```bash nix flake update ``` ### npm dependencies ```bash npm update npm run rebuild # Don't forget to rebuild! ```