fleetcode/NIX_SETUP.md

118 lines
3.4 KiB
Markdown

# 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!
```