Skip to main content

Development Setup

This guide will help you set up your development environment for contributing to Actual.

Prerequisites​

tip

If you prefer not to install Node and Yarn locally, you can use the Dev Container or run Docker Compose directly.

Before you begin, ensure you have the following installed:

  • Node.js: Version 22 or greater. You can download it from the Node.js website (we recommend the LTS version).

    • Consider using a version manager like nvm or asdf to manage multiple Node.js versions.
    • On Windows, during Node.js installation, be sure to select Automatically install the necessary tools from the Tools for Native Modules page. This is required to build better-sqlite3.

  • Yarn: Version 4.9.1 or greater. Yarn is the package manager used by Actual.

    • The project uses Yarn 4 workspaces (monorepo structure).

  • Git: Required for cloning the repository and version control.

Initial Setup​

  1. Clone the Actual repository:

    git clone https://github.com/actualbudget/actual.git
    cd actual

  2. Install all dependencies:

    yarn install

    This will install dependencies for all packages in the monorepo.

  3. Verify your setup by running type checking:

    yarn typecheck

Dev Container​

The repo includes a .devcontainer/ configuration that follows the Dev Containers spec. Any tool that supports the spec can use it — for example VS Code or Cursor (with the Dev Containers extension), JetBrains IDEs (via Gateway), GitHub Codespaces, or the @devcontainers/cli.

In an editor that supports the spec, open the cloned repo and accept the Reopen in Container prompt (or run the equivalent command from your editor's command palette). The container will build, yarn install will run automatically via postCreateCommand, and you'll be dropped into a shell with the toolchain ready.

To start the dev server, open a terminal inside the container and run:

yarn start

The dev server will be available at http://localhost:3001/. Most editors automatically forward the port from the container to your host.

Docker Compose​

For other editors, run from the repo root:

docker compose up --build

This starts a container that runs yarn start:browser on port 3001. Open http://localhost:3001/ in your browser.

note

The container mounts your repo at /app. If you've already run yarn install on your host, the native modules (better-sqlite3, bcrypt, electron, sharp) will be compiled for your host OS and won't work inside the Linux container. Either delete node_modules/ first and let the container reinstall, or run the dev container path above (which rebuilds them automatically).

Essential Development Commands​

All commands should be run from the root directory of the repository. Never run yarn commands from child workspace directories.

Type Checking​

# Run TypeScript type checking (ALWAYS run before committing)
yarn typecheck

Linting and Formatting​

# Check for linting and formatting issues
yarn lint

# Auto-fix linting and formatting issues
yarn lint:fix

Testing​

# Run all tests across all packages
yarn test

# Run tests without cache (for debugging)
yarn test:debug

For more details on testing, see the Testing Guide.

Starting Development Servers​

# Start browser development server
yarn start
# or explicitly:
yarn start:browser

# Start with sync server (for testing sync functionality)
yarn start:server-dev

# Start desktop app development
yarn start:desktop

Building​

# Build browser version
yarn build:browser

# Build desktop app
yarn build:desktop

# Build API package
yarn build:api

# Build CLI package
yarn build:cli

# Build sync server
yarn build:server

Workspace Structure​

Actual uses Yarn workspaces to manage a monorepo with multiple packages. For detailed information about each package, see the Project Structure documentation.

Running Workspace-Specific Commands​

To run commands for a specific workspace, use:

yarn workspace <workspace-name> run <command>

Examples:

# Run tests for @actual-app/core
yarn workspace @actual-app/core run test

# Start the docs development server
yarn workspace docs start

# Build the API package
yarn workspace @actual-app/api build

Common Development Tasks​

Running Specific Tests​

See Testing Guide.

Debugging​

# Run tests in debug mode (without cache)
yarn test:debug

# Run E2E tests with headed browser
yarn workspace @actual-app/web run playwright test --headed --debug accounts.test.ts

Type Checking​

TypeScript uses project references. Always run yarn typecheck from the root to check all packages.

Building for Production​

# Browser build
yarn build:browser

# Desktop build
yarn build:desktop

# API build
yarn build:api

# CLI build
yarn build:cli

# Sync server build
yarn build:server

Development Workflow​

When making changes:

  1. Read relevant files to understand the current implementation
  2. Make focused, incremental changes
  3. Run type checking: yarn typecheck
  4. Run linting: yarn lint:fix
  5. Run relevant tests
  6. Fix any linter errors that are introduced

For more details, see the Development Workflow section.

Troubleshooting​

If you encounter issues:

  • Type errors: Run yarn typecheck to see all type errors
  • Linter errors: Run yarn lint:fix to auto-fix many issues
  • Test failures: See the Testing Guide for debugging tips
  • Build failures: Clean build artifacts and reinstall dependencies: 
    rm -rf packages/*/dist packages/*/lib-dist packages/*/build
    yarn install

For more troubleshooting help, see the Troubleshooting Guide.

Next Steps​