eve-alpha/docs/SCRIPTS.md

EVE Development Scripts

Quick reference for all development scripts in the EVE project.

Running the Application

Linux/macOS

./run.sh

Windows

.\run.ps1

What it does:

• Checks for .env file (creates from template if missing)
• Checks for node_modules (installs if missing)
• Starts the Tauri development server with hot-reload
• Shows the app window with live code updates

Stop the server:

• Press Ctrl+C in the terminal
• Or run the kill script (see below)

Stopping the Application

Linux/macOS

./kill.sh

Windows

.\kill.ps1

What it does:

• Finds all EVE-related processes (Tauri, Vite, Cargo, etc.)
• Kills process trees cleanly
• Frees up ports (5173, 1420, etc.)
• Removes lock files

When to use:

• When Ctrl+C doesn't fully stop the server
• When you get "port already in use" errors
• When processes are stuck in the background
• Before switching branches or rebuilding

Setup Scripts

Linux/macOS

./setup.sh

Windows

.\setup.ps1

What it does:

• Detects your operating system
• Checks for Node.js, Rust, and dependencies
• Installs missing components (with permission)
• Sets up .env file
• Installs npm packages
• Verifies installation

See DEV_SETUP.md for detailed setup documentation.

npm Scripts

You can also use npm commands directly:

# Start development server (same as run.sh)
npm run tauri:dev

# Start frontend only (browser, no desktop app)
npm run dev

# Build for production
npm run tauri:build

# Build frontend only
npm run build

# Lint code
npm run lint

# Format code
npm run format

# Preview production build
npm run preview

Common Workflows

Start Fresh Development Session

./run.sh
# App starts with hot-reload enabled

Quick Restart

./kill.sh && ./run.sh
# Stops everything, then starts fresh

Clean Build

./kill.sh
rm -rf node_modules src-tauri/target
npm install
npm run tauri:build

Port Conflict Resolution

# If you get "address already in use" error
./kill.sh
# Then start again
./run.sh

Switch Branches

# Stop app first to avoid conflicts
./kill.sh
git checkout feature-branch
npm install  # Update dependencies if needed
./run.sh

Troubleshooting

"Permission denied" (Linux/macOS)

chmod +x run.sh kill.sh setup.sh

Scripts don't find processes (Linux/macOS)

The kill script uses pgrep, lsof, and ps. These should be available on most systems. If not:

# Ubuntu/Debian
sudo apt install procps lsof

# macOS (usually pre-installed)
# No action needed

PowerShell execution policy (Windows)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Processes still running after kill script

# Nuclear option - find and kill manually
ps aux | grep -E "vite|tauri|eve"
kill -9 <PID>

# Or on Windows
tasklist | findstr /i "node cargo"
taskkill /F /PID <PID>

Script starts but app window is blank

This is usually a graphics driver issue on Linux. The project includes a fix:

# The run script already includes this, but you can also run:
WEBKIT_DISABLE_COMPOSITING_MODE=1 npm run tauri:dev

Tips

1. Use run.sh for daily development - it's simpler than typing the full npm command
2. Use kill.sh liberally - it's safe and thorough
3. Run setup.sh once - when first setting up or after major changes
4. Check .env file - if the app shows "Configure Settings" on startup

Script Locations

All scripts are in the project root:

eve-alpha/
├── run.sh          # Start app (Linux/macOS)
├── run.ps1         # Start app (Windows)
├── kill.sh         # Stop app (Linux/macOS)
├── kill.ps1        # Stop app (Windows)
├── setup.sh        # Setup environment (Linux/macOS)
└── setup.ps1       # Setup environment (Windows)

---

Last Updated: October 6, 2025