Amp-Thread-ID: https://ampcode.com/threads/T-a6cf4bd2-36d0-4ef8-ada6-a8e2850fcacf Co-authored-by: Amp <amp@ampcode.com>
118 lines
3.4 KiB
Markdown
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!
|
|
```
|