Skip to main content

​
Overview

Flow Browser is an Electron-based web browser built with modern web technologies. It combines the power of Chromium with a custom React-based interface to deliver a privacy-focused browsing experience.
Flow Browser uses an embedded SQLite database (via better-sqlite3 and Drizzle ORM) and has no external backend services.

​
Project Structure

The codebase follows Electron’s multi-process architecture, with code organized into distinct directories:

src/main

Electron Main ProcessNode.js process that handles:
  • Window management
  • System integration
  • IPC communication
  • Browser engine control
  • Database operations

src/renderer

Frontend React ApplicationBrowser UI built with:
  • React 19
  • TailwindCSS 4
  • Radix UI components
  • Motion animations

src/preload

Preload ScriptsSecure bridge between main and renderer:
  • Context isolation
  • IPC communication
  • Safe API exposure

src/shared

Shared CodeCode used by both processes:
  • Type definitions
  • Constants
  • Utilities

​
Directory Details

DirectoryDescription
src/mainElectron main process code
src/rendererFrontend React application
src/preloadPreload scripts for secure IPC communication
src/sharedCode shared between main and renderer
docsDocumentation and guides
buildBuild assets (icons, etc.)
scriptsBuild and development scripts

​
Technology Stack

​
Frontend

React 19

Latest React with concurrent features

TailwindCSS 4

Utility-first CSS framework

Radix UI

Accessible component primitives

Motion

Animation library (motion/react)

​
Backend (Main Process)

Provides the browser engine and cross-platform desktop capabilities. Flow uses a Castlabs fork for Widevine DRM support.
  • better-sqlite3: Fast, synchronous SQLite bindings
  • Drizzle ORM: Type-safe database queries
  • Stores bookmarks, history, settings, and session data
  • electron-chrome-extensions: Custom fork (@iamevan/electron-chrome-extensions)
  • electron-chrome-web-store: Install extensions from Chrome Web Store
  • Full support for Chrome extension APIs
  • @ghostery/adblocker-electron: Native ad blocking
  • electron-webauthn: WebAuthn support for secure authentication
  • electron-context-menu: Secure context menu handling

​
Build Tools

  • electron-vite: Fast Vite-based Electron bundler
  • Vite 7: Lightning-fast build tool and dev server
  • TypeScript 5: Type safety across the codebase
  • electron-builder: Package and distribute the app
  • Bun: Package manager and task runner

​
Castlabs Electron Fork

Flow Browser uses a Castlabs fork of Electron instead of the standard Electron release. This is intentional and required for DRM support.

​
Why Castlabs?

The Castlabs fork includes Widevine CDM (Content Decryption Module) support, which allows Flow Browser to play DRM-protected content from services like:
  • Netflix
  • Spotify
  • Disney+
  • Amazon Prime Video
  • And other streaming platforms
In package.json, you’ll see: 
"electron": "https://github.com/castlabs/electron-releases#v40.1.0+wvcus"

​
Widevine VMP Signing

For production builds with full Widevine support, you need to:
  1. Create a Castlabs EVS account: EVS Account Setup
  2. Configure VMP signing credentials
  3. The build pipeline will automatically sign the application
Development builds work without VMP signing, but DRM content may have limitations.

​
Main Process Architecture

The main process is organized into controllers:

​
Controllers

  • windows-controller: Manages browser windows and navigation
  • sessions-controller: Handles Electron sessions and profiles
  • quit-controller: Manages application shutdown and cleanup
  • posthog-controller: Analytics and error tracking (privacy-focused)

​
IPC Communication

The src/main/ipc directory contains IPC handlers that expose safe APIs to the renderer process: 
// Example: Main process handler
ipcMain.handle('get-bookmarks', async () => {
  return await db.query.bookmarks.findMany();
});

// Renderer process call (via preload)
const bookmarks = await window.api.getBookmarks();

​
Renderer Architecture

The renderer process is a standard React application with:
  • Routes: Page components for different browser views
  • Components: Reusable UI components
  • Hooks: Custom React hooks for state management
  • Utils: Helper functions and utilities

​
Key Features

  • Profiles: Multiple user profiles with separate settings
  • Spaces: Organize tabs into workspaces
  • Command Palette: Quick access to browser functions
  • Sidebar: Bookmarks, history, and settings access
  • PDF Viewer: Built-in PDF viewing with @pdfslick/react

​
Animation System

Flow Browser uses motion/react, not framer-motion. Always import from motion/react.
import { motion } from 'motion/react';

<motion.div
  initial={{ opacity: 0 }}
  animate={{ opacity: 1 }}
>
  Content
</motion.div>

​
Testing Strategy

Flow Browser does not have automated test suites. Quality assurance is done through:
  • Type checking: bun typecheck (TypeScript)
  • Linting: bun lint (ESLint)
  • Manual testing: During development
  • CI validation: Automated checks on pull requests

​
Next Steps

Development Setup

Set up your development environment

Building

Learn how to build Flow Browser

Build docs developers (and LLMs) love

Get started for freeTalk to us