Development Setup

Set up your local development environment to contribute to AFFiNE.

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

Prerequisites

Required Software

macOS

# 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

Linux

# 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

Windows

# 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

1. Fork the repository

   Visit github.com/toeverything/AFFiNE and click Fork

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/AFFiNE.git
   cd AFFiNE
   
3. Add upstream remote

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

Install Dependencies

1. Install Node.js dependencies

   yarn install
   

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

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

1. Start PostgreSQL and Redis

   # Using Docker Compose
   cd .docker/selfhost
   docker compose up -d postgres redis
   
2. 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"
   
3. Run migrations

   yarn workspace @affine/server prisma migrate dev
   
4. 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

1. Create a branch

   git checkout -b feat/your-feature-name
   
2. Make changes

   Edit files and test locally

3. Run linter

   yarn lint:fix
   
4. Run tests

   yarn test
   
5. Commit changes

   git add .
   git commit -m "feat: add your feature"
   
6. 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

1. Clear Vite cache: rm -rf node_modules/.vite
2. Restart dev server
3. 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

1. Enable ESLint: Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
2. Enable Prettier: Settings → Languages & Frameworks → JavaScript → Prettier
3. 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