Skip to content

BUILD_TROUBLESHOOTING.md

Latest commit

 

History

History
142 lines (96 loc) · 3.7 KB

BUILD_TROUBLESHOOTING.md

File metadata and controls

142 lines (96 loc) · 3.7 KB
Raw

Bun Install/Build Troubleshooting Guide

If you encounter issues with bun install or bun run dist:* (such as hanging, timeout, or build failures).

Complete One-Click Install Script

#!/bin/bash
# JarvisX-Cowork One-Click Install Script

cd /path/to/JarvisX-Cowork

# Clean environment
rm -rf node_modules bun.lockb dist/

# Clear potentially corrupted Electron cache
rm -rf ~/Library/Caches/electron/electron-v*-darwin-arm64.zip 2>/dev/null

# Generate package-lock.json
npm install --package-lock-only

# Set mirrors and install
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

bun install

# Build (macOS ARM64 as example)
bun run dist:mac-arm64

echo "Build complete! App is located at dist/mac-arm64/JarvisX-Cowork.app"

Manual Configuration Step 1: Enable Mirror Configuration

Edit the .npmrc file in the project root and uncomment the mirror settings:

registry=https://registry.npmmirror.com
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/
better_sqlite3_binary_host=https://npmmirror.com/mirrors/better-sqlite3

Step 2: Create Bun Mirror Configuration

Create a bunfig.toml file in the project root:

[install]
registry = "https://registry.npmmirror.com"

Step 3: Generate package-lock.json (Critical Step)

electron-builder is not fully compatible with bun. A package-lock.json is needed to help resolve dependencies:

npm install --package-lock-only

Step 4: Set Proxy Environment Variables (If Using a Proxy)

Bun doesn't automatically read system proxy settings. You need to set environment variables manually:

# If you're using a proxy (e.g., Clash/Surge), set proxy environment variables
export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897

# If not using a proxy, make sure to clear proxy environment variables
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

Step 5: Install Dependencies

# Clean up old files
rm -rf node_modules bun.lockb dist/

# Set mirror environment variable and install
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ bun install

Step 6: If a Package Download Fails

If you see errors like FailedToOpenSocket downloading tarball xxx, use npm to install the failed package separately:

# For example, if caniuse-lite download fails
npm install caniuse-lite --save-dev

# Then re-run bun install
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ bun install

Step 7: If Build Fails with ENOENT Error (Critical)

If you see errors like ENOENT: no such file or directory, rename '...MacOS/Electron', the Electron cache may be corrupted and needs to be cleared:

# Clear corrupted Electron cache
rm -rf ~/Library/Caches/electron/electron-v*-darwin-arm64.zip
rm -rf ~/Library/Caches/electron/*darwin-arm64*

# Clear build artifacts
rm -rf dist/

# Then rebuild

Step 8: Build the Application

# macOS Apple Silicon
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/ \
bun run dist:mac-arm64

# macOS Intel
bun run dist:mac-x64

# Windows
bun run dist:win

# Linux
bun run dist:linux

Quick Reference Table

Issue Solution
bun install hangs Set proxy environment variables + use mirror
FailedToOpenSocket error Install failed package separately with npm
ENOENT: rename ...Electron error Clear Electron cache and rebuild
cannot find path for dependency Make sure package-lock.json exists