Development Setup

This guide walks you through setting up a development environment for AFFiNE.

Prerequisites

Required Software

macOS
Linux
Windows

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js (via fnm)
brew install fnm
fnm install 22
fnm use 22

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Yarn
corepack enable
corepack prepare yarn@stable --activate

# Install Node.js (via fnm)
curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22
fnm use 22

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Yarn
corepack enable
corepack prepare yarn@stable --activate

# Install build tools
sudo apt-get install build-essential

# Install Node.js
# Download from https://nodejs.org/

# Install Rust
# Download from https://www.rust-lang.org/tools/install

# Install Yarn
corepack enable
corepack prepare yarn@stable --activate

# Install Visual Studio Build Tools
# Download from https://visualstudio.microsoft.com/downloads/

On Windows, enable Developer Mode and configure Git for symbolic links:

git config --global core.symlinks true

Version Requirements

Tool	Version
Node.js	22.x (LTS)
Yarn	4.x
Rust	1.70+
Git	2.30+

Clone the Repository

Fork the repository

Visit github.com/toeverything/AFFiNE and click Fork

Clone your fork

git clone https://github.com/YOUR_USERNAME/AFFiNE.git
cd AFFiNE

Add upstream remote

git remote add upstream https://github.com/toeverything/AFFiNE.git

Install Dependencies

Install Node.js dependencies

yarn install

This installs all dependencies for the monorepo (may take 5-10 minutes).

Build native modules

# Build frontend native modules
yarn affine @affine/native build

# Build backend native modules
yarn affine @affine/server-native build

On macOS, use the system strip command, not the one from binutils.

Start Development Server

Web App

Start the web application:

yarn dev

This starts:

Web app on http://localhost:8080
Vite dev server with HMR

Desktop App

Start the Electron desktop app:

cd packages/frontend/apps/electron
yarn dev

This starts:

Electron app window
Dev server on http://localhost:8080
Auto-reload on changes

Backend Server

For full-stack development:

Start PostgreSQL and Redis

# Using Docker Compose
cd .docker/selfhost
docker compose up -d postgres redis

Configure environment

Create .env in packages/backend/server/:

.env

DATABASE_URL="postgresql://affine:affine@localhost:5432/affine"
REDIS_SERVER_HOST="localhost"
AFFINE_SERVER_EXTERNAL_URL="http://localhost:3010"

Run migrations

yarn workspace @affine/server prisma migrate dev

Start server

yarn workspace @affine/server dev

Server starts on http://localhost:3010

Project Structure

Understanding the codebase:

AFFiNE/
├── packages/
│   ├── backend/server/       # Backend NestJS app
│   ├── frontend/
│   │   ├── apps/web/         # Web application
│   │   ├── apps/electron/    # Desktop app
│   │   ├── core/             # Business logic
│   │   └── component/        # UI components
│   └── common/              # Shared utilities
├── blocksuite/              # Editor framework
├── tests/                   # E2E tests
└── tools/                   # Dev tools

Development Workflow

Creating a Feature

Create a branch

git checkout -b feat/your-feature-name

Make changes

Edit files and test locally

Run linter

yarn lint:fix

Run tests

yarn test

Commit changes

git add .
git commit -m "feat: add your feature"

Push and create PR

git push origin feat/your-feature-name

Commit Convention

Follow Conventional Commits:

feat: add new feature
fix: fix a bug
docs: update documentation
style: code style changes
refactor: refactor code
test: add or update tests
chore: maintenance tasks

Common Commands

Build Commands

# Build all packages
yarn build

# Build specific package
yarn workspace @affine/web build

# Build for production
yarn affine build

Linting & Formatting

# Run all linters
yarn lint

# Auto-fix issues
yarn lint:fix

# Just ESLint
yarn lint:eslint

# Just Prettier
yarn lint:prettier

Testing

# Run all tests
yarn test

# Run specific test file
yarn test path/to/test.spec.ts

# Run E2E tests
yarn workspace @affine-test/affine-local e2e

# Run with UI
yarn test:ui

Type Checking

# Type check all packages
yarn typecheck

Troubleshooting

Build Errors

Native module build fails

Make sure you have:

Rust installed: rustc --version
C++ compiler: gcc --version or Visual Studio Build Tools
Python 3: python --version

Try rebuilding:

yarn affine @affine/native build --force

Out of memory errors

Increase Node.js memory:

export NODE_OPTIONS="--max-old-space-size=8192"
yarn build

Port already in use

Kill the process on port 8080:

# Linux/macOS
lsof -ti:8080 | xargs kill -9

# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F

Dev Server Issues

Changes not reflecting

Clear Vite cache: rm -rf node_modules/.vite
Restart dev server
Hard refresh browser (Ctrl/Cmd + Shift + R)

WebSocket connection fails

Check that:

Backend server is running
Correct ports configured
No CORS issues
WebSocket not blocked by firewall

IDE Setup

VS Code

Recommended extensions:

ESLint
Prettier
TypeScript and JavaScript Language Features
Rust Analyzer
GraphQL

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

WebStorm

Enable ESLint: Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
Enable Prettier: Settings → Languages & Frameworks → JavaScript → Prettier
Set Node.js version: Settings → Languages & Frameworks → Node.js

Next Steps

Architecture Guide

Understand the codebase structure

Testing Guide

Learn how to write tests

Coding Guidelines

Follow our coding standards

Create Your First PR

Submit your first contribution

Get Started

Core Features

Desktop & Mobile

Self-Hosting

Contributing

Development Setup

Prerequisites

Required Software

Version Requirements

Clone the Repository

Install Dependencies

Start Development Server

Web App

Desktop App

Backend Server

Project Structure

Development Workflow

Creating a Feature

Commit Convention

Common Commands

Build Commands

Linting & Formatting

Testing

Type Checking

Troubleshooting

Build Errors

Dev Server Issues

IDE Setup

VS Code

WebStorm

Next Steps

Architecture Guide

Testing Guide

Coding Guidelines

Create Your First PR

Build docs developers (and LLMs) love

Get Started

Core Features

Desktop & Mobile

Self-Hosting

Contributing

​Prerequisites

​Required Software

​Version Requirements

​Clone the Repository

​Install Dependencies

​Start Development Server

​Web App

​Desktop App

​Backend Server

​Project Structure

​Development Workflow

​Creating a Feature

​Commit Convention

​Common Commands

​Build Commands

​Linting & Formatting

​Testing

​Type Checking

​Troubleshooting

​Build Errors

​Dev Server Issues

​IDE Setup

​VS Code

​WebStorm

​Next Steps

Architecture Guide

Testing Guide

Coding Guidelines

Create Your First PR

Build docs developers (and LLMs) love

Prerequisites

Required Software

Version Requirements

Clone the Repository

Install Dependencies

Start Development Server

Web App

Desktop App

Backend Server

Project Structure

Development Workflow

Creating a Feature

Commit Convention

Common Commands

Build Commands

Linting & Formatting

Testing

Type Checking

Troubleshooting

Build Errors

Dev Server Issues

IDE Setup

VS Code

WebStorm

Next Steps