# How to Build the Folia Electron Desktop App from Source

> Build the Folia Electron desktop app from source. Clone the chthollyphile/folia-major repo, install deps, build the front-end, and package your native installers.

- Repository: [冬霧/folia-major](https://github.com/chthollyphile/folia-major)
- Tags: how-to-guide
- Published: 2026-07-06

---

**Clone the repository, install dependencies with `npm ci`, build the Vite front-end with `npm run build`, and package the Electron app using `npm run build:electron` to generate native installers in the `release/` directory.**

The **Folia** desktop client is an Electron-based application powered by Vite and React, distributed in the `chthollyphile/folia-major` repository. Learning how to build the Folia Electron desktop app from source allows you to create custom installers for Windows, macOS, or Linux, contribuCode blocks to the project, or run development builds with hot-reload. This guide covers the complete build process using the actual npm scripts and configuration files found in the repository.

## Prerequisites

Before compiling, ensure your development environment meets these requirements:

- **Node.js ≥ 18** – Required for modern JavaScript features used throughout the codebase (confirmed by the version badge in the README).
- **npm** – The project includes a [`package-lock.json`](https://github.com/chthollyphile/folia-major/blob/main/package-lock.json) file, making `npm` the recommended package manager for deterministic installs.
- **Git** – Required to clone the source repository.
- **Platform-specific build tools** – Electron-builder requires native compilation tools:
  - **Linux**: Install `make`, `gcc`, and `libxcb` development headers.
  - **Windows**: Install Visual C++ Build Tools with the "Desktop development with C++" workload.
  - **macOS**: Xcode Command Line Tools are required for code signing and native modules.

## Step 1: Clone the Repository

Download the source code from GitHub and navigate into the project directory:

```bash
git clone https://github.com/chthollyphile/folia-major.git
cd folia-major

```

The repository contains the Electron main process at `electron/main.cjs`, the Vite-powered React frontend in `src/`, and the build configuration in [`package.json`](https://github.com/chthollyphile/folia-major/blob/main/package.json).

## Step 2: Install JavaScript Dependencies

Use npm to install the exact dependency versions defined in the lockfile:

```bash
npm ci

```

Alternatively, you can run `npm install` if you need to update dependencies, though `npm ci` is recommended for reproducible builds. This command installs both runtime dependencies and development tools including `electron` and `electron-builder`.

## Step 3: Configure Environment Variables (Optional)

If you plan to run the application with AI-powered features or Netease API integration, copy the example environment file and configure your keys:

```bash
cp .env.example .env.local

# Edit .env.local to add your API credentials

```

**Note:** This step is **optional for building**. You can compile the binary without these variables, but certain features will be unavailable at runtime. See [`docs/technical.md`](https://github.com/chthollyphile/folia-major/blob/main/docs/technical.md) for the complete variable list.

## Step 4: Build the Vite Front-End Assets

Folia uses Vite to bundle the React user interface. Compile the static assets that Electron will load:

```bash
npm run build

```

This executes `"build": "vite build"` from [`package.json`](https://github.com/chthollyphile/folia-major/blob/main/package.json), outputting optimized files to the `dist/` directory. These assets are referenced by the Electron main process when running the packaged application.

## Step 5: Package the Electron Application

The repository provides several npm scripts for different build scenarios. Choose the appropriate command based on your needs:

- **`npm run dev:electron`** – Starts Vite in development mode with hot-reload and launches Electron for debugging.
- **`npm run dev:electron:dist`** – Builds the production bundle first, then runs the packaged binary locally to test the production build.
- **`npm run build:electron:dir`** – Creates a directory distribution without installers (useful for Linux testing).
- **`npm run build:electron`** – Runs the full `electron-builder` process to generate native installers for your current platform.

To create the final installer for your operating system:

```bash
npm run build
npm run build:electron

```

The `electron-builder` configuration in [`package.json`](https://github.com/chthollyphile/folia-major/blob/main/package.json) (under the `build` field) specifies target formats, icons, and extra resources to include. This process bundles the Vite output from `dist/` with the Electron runtime and the main process code from `electron/main.cjs`.

## Step 6: Locate the Build Output

After successful compilation, find your native installers in the `release/` directory (defined by `build.directories.output` in [`package.json`](https://github.com/chthollyphile/folia-major/blob/main/package.json)):

- **Windows**: `release/Folia-Setup-<version>.exe` (NSIS installer)
- **macOS**: `release/Folia-<version>.dmg` (disk image) or `.zip`
- **Linux**: `release/<name>-<version>-linux-<arch>.tar.gz`, `.deb`, `.rpm`, or `.AppImage`

On Linux, you may need to mark the AppImage as executable before running:

```bash
chmod +x release/folia-major-*.AppImage
./release/folia-major-*.AppImage

```

## Cross-Platform Build Considerations

While `electron-builder` can target multiple platforms, creating installers for an OS requires building on that OS or using specific workarounds:

- **Windows from macOS/Linux**: Install **Wine** and **NSIS** (`brew install wine nsis` or `apt install wine nsis`).
- **macOS from Linux/Windows**: Requires a macOS host or CI service; macOS binaries cannot be built on other platforms due to code signing requirements.
- **Linux from Windows/macOS**: Generally works out-of-the-box, though you may need `dpkg` or `rpm` tools for specific package formats.

Force a specific target using command-line arguments:

```bash
npm run build:electron -- --linux deb
npm run build:electron -- --win nsis

```

## Summary

- **Clone** the `chthollyphile/folia-major` repository and ensure Node.js ≥ 18 is installed.
- Run **`npm ci`** to install exact dependency versions from the lockfile.
- Execute **`npm run build`** to compile Vite assets into `dist/`.
- Use **`npm run build:electron`** to generate native installers in the `release/` directory.
- The Electron main process entry point is located at **`electron/main.cjs`** and handles window management, tray icons, and IPC communication.
- Environment variables in `.env.local` are optional for building but required for AI features at runtime.

## Frequently Asked Questions

### Do I need API keys to build the Folia Electron app?

No. API keys for AI features or Netease integration are only required if you intend to run the application with those features enabled. The build process completes successfully without any environment variables, though certain cloud-based functions will be unavailable in the resulting binary.

### What is the difference between `npm run dev:electron` and `npm run build:electron`?

`npm run dev:electron` starts a development server with hot-reload, ideal for coding and debugging changes in real-time. `npm run build:electron` creates a production-ready installer using `electron-builder`, bundling optimized assets and the Electron runtime for distribution to end users.

### Why does the build fail on Linux with errors about `libxcb`?

Electron applications require native dependencies that link to system libraries. On Linux distributions, install the X11 client-side library development files (`libxcb-devel` or `libxcb1-dev` depending on your package manager) before running `npm install` to ensure native Node modules compile correctly.

### Can I build a Windows installer from macOS or Linux?

Yes, but you must install **Wine** and **NSIS** (Nullsoft Scriptable Install System) on your build machine. Run `npm run build:electron -- --win nsis` after installing these tools. Note that macOS binaries (.dmg) cannot be built on non-macOS systems due to Apple's code signing requirements.