Building from Source

Relevant source files

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

• package.json
• setup.js
• README.md
• README_zh.md
• main.js
• CHANGELOG_v1.2.3.md

This document provides a comprehensive guide for developers on how to build the GeekEZ Browser from its source code. It covers the initial setup, dependency installation, running the application in a development environment, and packaging it for distribution across different operating systems.

The build process is managed by NPM scripts and relies on electron-builder for packaging. A crucial part of the setup is the postinstall script, which automatically downloads the required versions of Xray-core and the Chromium browser, ensuring that all necessary binaries are in place before the application is run or built.

Prerequisites

Before you begin, ensure you have the following software installed on your system:

• Node.js (version 16 or higher)
• Git

Sources: README.md:100, README_zh.md:95

Installation and Setup

The installation process is initiated by cloning the repository and running npm install. This not only installs the Node.js dependencies listed in package.json but also triggers a custom postinstall script to fetch necessary external binaries.

NPM Scripts

The project uses several NPM scripts defined in package.json to manage the development, setup, and build lifecycle.

Script	Command	Description
start	electron .	Starts the application in development mode by running the main Electron process (main.js).
postinstall	node setup.js	Automatically runs after npm install. Downloads and extracts Xray-core and the specified Chromium browser version.
build:win	electron-builder --win --x64	Packages the application for 64-bit Windows.
build:mac	electron-builder --mac --arm64 --x64	Packages the application for macOS (ARM64 and x64 universal).
build:linux	electron-builder --linux	Packages the application for Linux.

Sources: package.json:7-13

Post-install Dependency Fetching

The setup.js script is executed automatically after npm install. Its primary role is to download and place the correct versions of Xray-core and Chromium into the resources directory. This ensures the application has its core dependencies without requiring manual downloads.

The following diagram illustrates the workflow of the setup.js script.

This diagram shows the automated process of fetching Xray-core and Chromium based on network location.
Sources: setup.js, package.json:8

Key steps in this process include:

1. Network Check: The script pings google.com to determine if it's on a global network or behind a firewall (e.g., in China).
2. URL Construction: Based on the network check, it uses either the direct GitHub release URL or a proxied mirror (GH_PROXY) to download Xray-core. For Chromium, it sets the baseUrl to a mirror if not on a global network.
3. Platform Detection: It identifies the operating system (win32, darwin, linux) and architecture (x64, arm64) to download the correct binary package.
4. Download and Extraction: The script downloads the zipped binaries, shows a progress bar in the console, extracts them to their respective directories (resources/bin for Xray, resources/puppeteer for Chrome), and sets executable permissions where necessary.

Sources: setup.js:46-64, 74-81, 127-164

Running in Development Mode

To run the application for development or testing without packaging it, use the start script.

npm start

This command executes electron ., which starts the Electron main process defined in main.js. The application will launch with access to developer tools, and any changes to the source files will require a manual restart to take effect.

Sources: package.json:7, README.md:111

Packaging for Distribution

To create distributable installers or packages for different operating systems, use the build:* scripts. These scripts leverage electron-builder to bundle the application, its dependencies, and the downloaded binaries into a polished, platform-specific format.

Build Configuration

The build process is configured in the build section of package.json.

Configuration Key	Description
appId	The unique application identifier (com.geekez.browser).
productName	The name of the application displayed to the user (GeekEZ Browser).
directories.output	The directory where build artifacts are placed (dist).
files	An array of glob patterns specifying which files to include in the package. It explicitly excludes development files and build output.
extraResources	Specifies additional resources to be copied into the application package. This is critical for including the Xray and Chromium binaries.
win, mac, linux	Platform-specific configurations, such as the target package format (nsis, dmg, AppImage) and icon files.
nsis	Configuration for the NSIS (Windows) installer, allowing for a desktop shortcut and changeable installation directory.

Sources: package.json:14-53

The following diagram shows the high-level packaging process when a build script is run.

This diagram illustrates how electron-builder uses the configuration in package.json to create a distributable package.
Sources: package.json:9, 14-39

Included Resources

The extraResources configuration ensures that the binaries downloaded during the postinstall step are included in the final application package. The application locates these binaries at runtime using paths relative to process.resourcesPath.

// From: main.js
const isDev = !app.isPackaged;
const BIN_DIR = isDev ? path.join(__dirname, 'resources', 'bin') : path.join(process.resourcesPath, 'bin');
const BIN_PATH = path.join(BIN_DIR, process.platform === 'win32' ? 'xray.exe' : 'xray');

// ...

function getChromiumPath() {
    const basePath = isDev ? path.join(__dirname, 'resources', 'puppeteer') : path.join(process.resourcesPath, 'puppeteer');
    // ... logic to find chrome.exe or equivalent
}

This code shows how the application dynamically resolves the path to its bundled binaries depending on whether it's running in development (isDev) or as a packaged application.
Sources: main.js:15-28, package.json:28-39