Skip to content

development.md

Latest commit

 

History

History
143 lines (100 loc) · 3.4 KB

development.md

File metadata and controls

143 lines (100 loc) · 3.4 KB
Raw
description Developer environment setup covering IDE configuration, Windows symlink support, and project install steps

🖥️ Develop

IDE Setup

VSCode like

Zed

  1. Install the Oxc extension for Oxfmt and Oxlint.
  2. Copy the example settings file to your local Zed config: 
    cp .zed/settings.json.example .zed/settings.json
  3. Customize .zed/settings.json as needed (it is git-ignored).

Windows: Enable Symlinks

This project uses symlinks to synchronize files such as AGENTS.md and skills. Windows developers must enable symlink support before cloning:

  1. Enable Developer Mode (Settings → Update & Security → For developers), or grant SeCreateSymbolicLinkPrivilege via secpol.msc.
  2. Configure Git: 
    git config --global core.symlinks true
  3. Clone (or re-clone) the repository after enabling symlink support.

Project Setup

Install

pnpm install

Setup Node.js

The required Node.js version is defined in .node-version. Use a version manager like nvm or fnm to install it automatically:

nvm install

Setup pnpm

The pnpm version is locked in the packageManager field of package.json. Just enable corepack and it will use the correct version automatically:

corepack enable

Install Dependencies

pnpm install

ENV

cp .env.example .env

Start

pnpm dev

By default, development runs append Dev to Electron's default userData directory, keeping local dev data separate from packaged app data. To run an entirely isolated development profile, set an absolute profile root in .env:

CS_DEV_PROFILE_ROOT=/absolute/path/to/cherry-profile

This keeps Cherry home, BootConfig, legacy config discovery, Electron userData, and logs under that root. The root cannot be relative or the filesystem root, and packaged builds ignore it. When set, it takes precedence over CS_DEV_USER_DATA_SUFFIX.

Data Isolated location
Cherry home and BootConfig {profileRoot}/.cherrystudio
Electron userData {profileRoot}/userData
Application logs {profileRoot}/logs

For lightweight isolation of multiple development instances, give each instance a unique userData suffix. You can set it in .env:

CS_DEV_USER_DATA_SUFFIX=DevQuito

Or pass it inline when starting a dev instance:

CS_DEV_USER_DATA_SUFFIX=DevQuito pnpm dev
CS_DEV_USER_DATA_SUFFIX=DevParis pnpm dev

The suffix must be a single path component (no path separator, drive colon, * ? " < > |, control character, or trailing dot). Blank values fall back to Dev; anything else that breaks those rules stops the dev run instead of falling back, so two instances never end up sharing one directory.

Debug

pnpm debug

Then input chrome://inspect in browser

Test

pnpm test

Build

# For windows
$ pnpm build:win

# For macOS
$ pnpm build:mac

# For Linux
$ pnpm build:linux

For architecture-specific commands and the pinned better-sqlite3 prebuild workflow, see Linux Packaging.