How to Build the Folia Electron Desktop App from Source

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 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:

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.

Step 2: Install JavaScript Dependencies

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

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:

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 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:

npm run build

This executes "build": "vite build" from 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:

npm run build
npm run build:electron

The electron-builder configuration in 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):

• 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:

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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}