fleetcode/NIX_SETUP.md

3.4 KiB

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:

    nix develop
    
  2. First-time setup:

    npm install
    npm run rebuild  # Rebuild native modules for Electron
    
  3. 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:

  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:

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!