How to Configure AppFlowy for Local Development and Testing: Complete Setup Guide

Run the platform-specific install script (install_linux.sh, install_windows.sh, or install_macos.sh) to automate Rust, Flutter 3.27.4, and native dependency setup, then execute cargo make appflowy-linux-dev (or the platform equivalent) to build and launch the desktop application.

AppFlowy is an open-source Rust and Flutter desktop application for note-taking and project management. To configure AppFlowy for local development and testing, you will use automated shell scripts and cargo-make tasks that handle cross-platform dependency management and build orchestration.

Prerequisites and Environment Overview

Supported Platforms

AppFlowy builds natively on Linux, macOS, and Windows. The repository provides dedicated setup scripts for each operating system located in frontend/scripts/install_dev_env/.

Core Technology Stack

• Rust: Backend logic and native performance-critical code
• Flutter 3.27.4: UI framework (enforced version)
• cargo-make: Build automation and task runner
• Flutter-Rust bridge: FFI bindings between Dart and Rust

Automated Setup with Install Scripts

The fastest way to configure your environment is using the provided shell scripts that install Rust, Flutter, system libraries, and development tools.

Linux Environment Setup

Run frontend/scripts/install_dev_env/install_linux.sh to automate the entire Linux setup:

bash frontend/scripts/install_dev_env/install_linux.sh

This script performs the following actions (as implemented in the source):

• Lines 22-38: Checks for Rust and installs it via rustup if missing
• Lines 38-57: Verifies Flutter installation and enforces version 3.27.4
• Lines 66-92: Installs native Linux libraries including keybinder-3.0-dev, libnotify-dev, and libmpv-dev
• Lines 94-98: Configures Git hooks path to .githooks and installs go-gitlint for commit linting
• Lines 106-115: Installs cargo-make and duckscript_cli build tools
• Lines 116-119: Executes cargo make appflowy-flutter-deps-tools to prepare the Flutter-Rust bridge

Windows Environment Setup

For Windows development, use the equivalent PowerShell/Batch script:

frontend/scripts/install_dev_env/install_windows.sh

This script installs the Windows equivalents of the Linux native libraries and configures the MSVC build toolchain.

macOS Environment Setup

macOS developers should run the macOS-specific install script to configure Xcode command line tools, Homebrew dependencies, and the Apple Silicon or Intel build targets.

Configuring the Flutter-Rust Bridge

After running the install script, you must generate the FFI bindings between Flutter and Rust. This is handled automatically by the install script, but you can run it manually:

cargo make appflowy-flutter-deps-tools

This task downloads required Rust crates (such as flowy-net and appflowy-backend) and generates the Dart bindings used by the Flutter UI layer.

Building and Running AppFlowy Locally

Development Build Configuration

Build configurations are defined in frontend/Makefile.toml as environment blocks. For example, the Linux development configuration (lines 36-45) sets:

• Cargo profile: development
• Target triple: x86_64-unknown-linux-gnu
• Library type: cdylib
• Output directories for Flutter integration

Similar blocks exist for development-mac-arm64 and Windows targets.

Running the Desktop Application

To build and launch AppFlowy in development mode, run the platform-specific cargo-make task:

Linux:

cargo make appflowy-linux-dev

macOS:

cargo make appflowy-macos-dev

Windows:

cargo make appflowy-windows-dev

These tasks (defined in frontend/scripts/makefile/desktop.toml, lines 12-22) compile the Rust backend, run flutter build for the platform, and launch the resulting desktop binary.

Fast Iteration Workflows

Rebuilding Only the Rust Backend

For rapid development when only Rust code has changed, avoid the full Flutter rebuild by using the test-build task:

cargo make test-build

This task (defined in frontend/Makefile.toml, lines 304-309) recompiles the Rust crates with the dart feature enabled without regenerating Flutter assets, significantly reducing iteration time.

Running Unit Tests

To execute the Rust test suite:

cargo make test-build
cargo test --all

This ensures the latest Rust code is built with the correct configuration before running the full test suite across all workspace crates.

Summary

• Use automated scripts: Run install_linux.sh, install_windows.sh, or the macOS equivalent to install Rust, Flutter 3.27.4, and system dependencies.
• Leverage cargo-make: Build and run the application with cargo make appflowy-linux-dev (or platform equivalent) defined in frontend/scripts/makefile/desktop.toml.
• Optimize iteration: Use cargo make test-build for fast Rust-only rebuilds during development.
• Verify environment: Ensure Flutter-Rust bridge generation completes via cargo make appflowy-flutter-deps-tools before building.

Frequently Asked Questions

What version of Flutter is required for AppFlowy development?

AppFlowy requires Flutter 3.27.4 exactly. The install scripts enforce this version check (see install_linux.sh lines 38-57) and will warn or checkout the correct version if a different SDK is detected. Using a different Flutter version may cause build failures or runtime errors in the Flutter-Rust bridge.

Can I develop AppFlowy on Windows or macOS?

Yes, AppFlowy supports development on Linux, macOS, and Windows. Each platform has a dedicated install script in frontend/scripts/install_dev_env/ (e.g., install_windows.sh for Windows). The cargo-make tasks in frontend/scripts/makefile/desktop.toml provide platform-specific build commands: appflowy-macos-dev for macOS and appflowy-windows-dev for Windows.

How do I update the Flutter-Rust bridge after adding new dependencies?

Run cargo make appflowy-flutter-deps-tools to regenerate the FFI bindings and fetch new Rust crates. This task (executed automatically by the install scripts) updates the generated Dart code in the Flutter project to match the current Rust interface. You must run this whenever you add new Rust dependencies or modify the public API of the Rust backend crates like flowy-net or appflowy-backend.

Why does the build fail with missing native library errors?

Missing native library errors typically indicate that the platform-specific system dependencies were not installed. On Linux, ensure keybinder-3.0-dev, libnotify-dev, and libmpv-dev are installed (handled by install_linux.sh lines 66-92). On Windows, verify that the MSVC build tools and Windows SDK are installed. Re-running the appropriate install script usually resolves these missing dependency issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}