Skip to main content

​
Prerequisites

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

Node.js v22+

Download from nodejs.org

Bun v1.2.0+

Install from bun.sh

​
System Dependencies

Electron uses node-gyp to build native modules. You need to install platform-specific dependencies for native module compilation.
Install build tools and Python:
# Debian/Ubuntu
sudo apt-get install build-essential python3

# Fedora
sudo dnf install make gcc gcc-c++ python3

# Arch
sudo pacman -S base-devel python
For more details on node-gyp dependencies, see the official installation guide.

​
Getting Started

1

Clone the Repository

git clone https://github.com/MultiboxLabs/flow-browser.git
cd flow-browser
2

Install Dependencies

bun install
The postinstall script will automatically run electron-builder install-app-deps to rebuild native modules for Electron.
3

Start Development

Choose your preferred development mode:
# Start the application in preview mode (no hot reload)
bun start

​
Development Workflow

​
Available Commands

Here are the essential commands you’ll use during development:
TaskCommandDescription
Install dependenciesbun installInstall all project dependencies
Developmentbun devStart development mode with hot reload
Watch modebun dev:watchStart with file watching (recommended)
Lintbun lintRun ESLint to check code quality
Type checkbun typecheckRun TypeScript type checking
Formatbun formatFormat code with Prettier
Previewbun startStart in preview mode (production-like)

​
Before Committing

Always run these commands before pushing changes to avoid CI failures:
# Run all checks
bun run lint
bun run typecheck
bun run format

​
First Launch

On first launch, Flow Browser will show an onboarding wizard. You must complete this before the main browser window appears.

​
Troubleshooting

​
Native Module Build Failures

If you encounter errors during bun install related to native modules:
  1. Ensure you have all system dependencies installed (see above)
  2. Try clearing the cache and reinstalling: 
    bun run reset
bun install

​
Electron Display Issues on Linux

If running in a headless environment:
  • GLib-GObject and D-Bus warnings are harmless and can be ignored
  • The VM should have a display set (e.g., DISPLAY=:1)
  • No xvfb-run wrapper is needed in most cloud environments

​
Next Steps

Architecture

Learn about Flow Browser’s architecture

Building

Build Flow Browser for production

Build docs developers (and LLMs) love

Get started for freeTalk to us