Skip to main content
AFFiNE’s desktop app is built with Electron, providing a native experience across Windows, macOS, and Linux with powerful features like offline support, native integrations, and automatic updates.

​
Platform Support

Windows

Windows 10 and later (64-bit)

macOS

macOS 10.15 Catalina and later

Linux

AppImage, .deb, and AUR packages

​
Key Features

​
Offline-First

The desktop app is fully functional offline:
  • All workspaces stored locally in IndexedDB
  • Automatic sync when connection restored
  • No internet required for core features
  • Local-first architecture with Y.js CRDT

​
Native Integration

The desktop app integrates deeply with your operating system:
  • System tray support
  • Native notifications
  • File associations for .affine files
  • Protocol handler for affine:// links
  • Windows 11 snap layouts
  • Menu bar integration
  • Touch Bar support
  • Native notifications
  • Dock badge for unread items
  • Spotlight integration
  • Apple Silicon optimization
  • System tray icon
  • Desktop notifications
  • XDG desktop entry
  • Wayland and X11 support
  • Protocol handler registration

​
Auto-Updates

The desktop app updates automatically in the background:
  • Updates downloaded silently
  • Notifies when update ready
  • Installs on next restart
  • Can opt-out in settings
  • Support for beta and canary channels

​
Installation

See our installation guide for detailed instructions for each platform.

​
Architecture

The AFFiNE desktop app consists of:

​
Main Process

The main process manages:
  • Window Management: Create, manage, and close windows (src/main/windows-manager/)
  • Native Modules: Rust-based native bindings for performance (packages/frontend/native/)
  • Protocol Handlers: Handle affine:// deep links
  • Auto-Updates: Check and apply updates via electron-updater
  • IPC Bridge: Communication with renderer process
main/index.ts
import { app, protocol } from 'electron';
import { WindowsManager } from './windows-manager';
import { registerProtocol } from './protocol';

app.whenReady().then(() => {
  registerProtocol();
  WindowsManager.createWindow();
});

​
Renderer Process

The renderer runs the AFFiNE web app with additional capabilities:
  • Electron API: Access to native features via preload script
  • Local Storage: Enhanced storage with native filesystem access
  • Performance: Native modules for Y.js encoding/decoding

​
Preload Scripts

Security bridge between main and renderer:
preload/electron-api.ts
import { contextBridge, ipcRenderer } from 'electron';

contextBridge.exposeInMainWorld('affine', {
  openExternal: (url: string) => ipcRenderer.invoke('open-external', url),
  getPath: (name: string) => ipcRenderer.invoke('get-path', name),
  // ... more APIs
});

​
Native Modules

AFFiNE uses Rust-based native modules built with napi-rs for performance-critical operations:

​
Y.js Encoding/Decoding

Fast binary encoding for CRDT updates: 
import { encodeStateVector, mergeUpdates } from '@affine/native';

const encoded = encodeStateVector(stateVector);
const merged = mergeUpdates([update1, update2]);

​
Workspace Scanning

Fast filesystem operations: 
import { scanWorkspaces } from '@affine/native';

const workspaces = await scanWorkspaces(rootPath);

​
Storage

​
Data Location

User data is stored in platform-specific locations: 
%APPDATA%\AFFiNE\workspaces\

​
Storage Structure

workspaces/
  {workspace-id}/
    metadata.json
    docs/
      {doc-id}.yjs
    blobs/
      {blob-hash}

​
Configuration

​
App Settings

Settings are stored in:
  • Windows: %APPDATA%\AFFiNE\config.json
  • macOS: ~/Library/Application Support/AFFiNE/config.json
  • Linux: ~/.config/AFFiNE/config.json

​
Command-Line Flags

Customize behavior with flags: 
# Enable DevTools
affine --dev

# Custom data directory
affine --user-data-dir=/custom/path

# Disable GPU acceleration
affine --disable-gpu

# Force software rendering
affine --disable-software-rasterizer

​
Performance

​
Native Optimization

The desktop app includes several performance optimizations:
  • V8 Snapshot: Faster startup with precompiled code
  • Lazy Loading: Load features on-demand
  • Native Encoding: Rust-based Y.js operations
  • IndexedDB: Fast local storage
  • Web Workers: Offload heavy computation

​
Memory Management

Electron apps can be memory-intensive. AFFiNE implements:
  • Automatic garbage collection tuning
  • Image lazy loading
  • Virtual scrolling for large lists
  • Workspace unloading for inactive tabs

​
Troubleshooting

​
App Won’t Start

Delete the app data directory and restart:
  • Windows: %APPDATA%\AFFiNE
  • macOS: ~/Library/Application Support/AFFiNE
  • Linux: ~/.config/AFFiNE
Logs are stored in:
  • Windows: %APPDATA%\AFFiNE\logs
  • macOS: ~/Library/Logs/AFFiNE
  • Linux: ~/.config/AFFiNE/logs

​
Sync Issues

If sync isn’t working:
  1. Check internet connection
  2. Verify workspace is cloud-enabled
  3. Check sync status in settings
  4. Try manual sync (Cmd/Ctrl + Shift + S)

​
Performance Issues

1

Disable hardware acceleration

Settings → Advanced → Disable GPU acceleration
2

Reduce workspace count

Close unused workspaces to free memory
3

Clear cache

Settings → Advanced → Clear cache
4

Update to latest version

Check for updates in Help menu

​
Development

To build the desktop app locally:
1

Install dependencies

yarn install
2

Build native modules

yarn affine @affine/native build
3

Start development server

yarn workspace @affine/electron dev
4

Package for distribution

yarn workspace @affine/electron make

Installation

Download and install the desktop app

Mobile Apps

Learn about iOS and Android apps

Contributing

Build and contribute to the desktop app

Electron Documentation

Learn more about Electron