Dependency Management (setup.js)

Relevant source files

The following files were used as context for generating this wiki page:

• setup.js
• package.json
• main.js
• README.md
• README_zh.md
• renderer.js
• index.html
• preload.js

The setup.js script is a crucial part of the GeekEZ Browser's bootstrapping process. It is designed to automatically download and configure the necessary external binary dependencies required for the application to run, specifically the Xray-core networking engine and a fixed version of the Chrome browser. This automation simplifies the initial setup for developers running the application from source.

The script is triggered automatically after a developer runs npm install, thanks to the postinstall hook defined in package.json. It intelligently handles different operating systems and network environments to ensure a smooth and reliable setup experience.

Sources: setup.js, package.json:8, README.md:83-86

Execution Trigger

The setup process is initiated by the postinstall script in the project's package.json file. This is a standard npm hook that executes a command after the npm install process successfully completes.

"scripts": {
  "start": "electron .",
  "postinstall": "node setup.js",
  "build:win": "electron-builder --win --x64",
  "build:mac": "electron-builder --mac --arm64 --x64",
  "build:linux": "electron-builder --linux"
},

Sources: package.json:7-8

This configuration ensures that any developer setting up the project will automatically have the required binary dependencies fetched and placed in the correct directory without manual intervention.

Core Dependencies

The setup.js script manages two primary external binary dependencies that are not available as standard npm packages.

Dependency	Version / Build ID	Purpose	Destination Directory
Xray-core	v24.11.30	Provides the underlying networking engine for proxying traffic, supporting protocols like VMess, VLESS, etc.	resources/bin
Chrome	129.0.6668.58	The browser binary used by Puppeteer to create isolated browsing environments.	resources/puppeteer

Sources: setup.js:10, setup.js:174, setup.js:175, main.js:15-16, main.js:43

Setup Process Flow

The script executes a series of steps to download, extract, and configure the dependencies. The overall logic is contained within the main() async function.

This diagram illustrates the execution flow of the setup.js script.

Network-Aware Downloading

A key feature of the setup script is its ability to adapt to the user's network environment. This is particularly important for downloading assets from GitHub, which can be slow or blocked in certain regions.

1. Network Check: The checkNetwork() function attempts to make a HEAD request to https://www.google.com.
2. URL Selection:
   • If the request is successful, it's considered a "Global" network, and direct GitHub release URLs are used.
   • If the request fails or times out, it's assumed the user is in a region like China ("CN"). In this case, a proxy URL (GH_PROXY) is prepended for Xray-core, and a mirror URL (https://npmmirror.com/mirrors/chrome-for-testing) is used for downloading Chrome.

This sequence diagram shows the interaction between the script and external services based on the network check.

Platform-Specific Logic

The script correctly identifies the user's operating system and CPU architecture to download the appropriate binary for Xray-core. The getPlatformInfo() function handles this logic.

Platform (os.platform())	Architecture (os.arch())	Xray Asset Name
win32	x64	Xray-windows-64.zip
win32	ia32	Xray-windows-32.zip
darwin	arm64	Xray-macos-arm64-v8a.zip
darwin	x64	Xray-macos-64.zip
linux	x64	Xray-linux-64.zip
linux	ia32	Xray-linux-32.zip

After extraction on macOS and Linux, the script also ensures the Xray binary is executable by running fs.chmodSync(..., '755').

Sources: setup.js:63-79, setup.js:189

Download & Extraction

The script provides a user-friendly command-line interface during the download process.

• downloadFile(url, dest, label): This function handles the download, including following HTTP redirects. It pipes the response to a file stream.
• showProgress(received, total, startTime, prefix): As data chunks are received, this function is called to render a dynamic progress bar in the console. It calculates and displays the percentage complete, downloaded size, total size, and download speed.
• extractZip(zipPath, destDir): This function unpacks the downloaded archives. It uses platform-specific commands for robustness:
  • Windows: powershell -command "Expand-Archive ..."
  • macOS/Linux: unzip -o ...

After successful extraction, the temporary .zip file is deleted.

Sources: setup.js:24-52, setup.js:94-135, setup.js:137-150

Summary

The setup.js script is an essential automation tool that ensures the GeekEZ Browser's critical binary dependencies are correctly installed. By running automatically after npm install, it provides a seamless developer experience. Its intelligent handling of network conditions and operating systems makes the setup process robust and reliable across different environments. This script is fundamental to the project's architecture, as the main application logic in main.js directly relies on the presence of the Xray and Chrome binaries in the resources directory.

Sources: setup.js, main.js:15-17, main.js:43-54