Local Development Setup

Architectural Foundation: Node.js · pnpm · Turborepo

Description: Local development setup guide covering prerequisites (Node.js v20+, pnpm v8), workspace installation, and Turborepo-orchestrated development and build scripts.

🚀 Getting Started

Prerequisites

Ensure your local environment matches the following versions to avoid compatibility issues:

• Node.js: v20+ (tested with v24.11.1) — required for the --import tsx flag used by the desktop prebuild script
• pnpm: v8.15.6 (Enforced via the packageManager field in package.json)

Installation

Install all dependencies from the root directory:

pnpm install

🛠 Usage & Scripts

This repository uses Turborepo to orchestrate tasks efficiently. All commands are executed from the root.

Development

Command	Description
pnpm dev	Start all applications (web and docs-dev) in parallel
pnpm dev:web	Start only the Main Web App (strictly at http://localhost:5173)
pnpm dev:landing	Start the Public Landing App (strictly at http://localhost:3000)
pnpm dev:docs-dev	Start VitePress for documentation development (strictly at http://localhost:6060)
pnpm dev:desktop	Start the Web App + Electron in parallel for desktop development

> **Port Topology**: `electron-vite` dynamically allocates a background port (usually `5174`) for its internal renderer shell during `pnpm dev:desktop`. We strictly isolate `web` (`5173`) and `landing` (`3000`) onto separate port ranges to prevent race conditions during parallel execution.

Building & Quality

Command	Description
pnpm build	Build all apps and packages using Turbo cache
pnpm build:web	Build only the web application
pnpm build:landing	Build only the landing page
pnpm build:docs-dev	Build only the docs-dev application
pnpm build:desktop	Build the web app, then compile the Electron app
pnpm test	Run unit tests (Vitest) across all packages
pnpm test:e2e:web	Run Playwright E2E for apps/web (starts Vite on port 4173)
pnpm lint	Run ESLint across the workspace
pnpm format	Format code using Prettier

🚀 Desktop Packaging & Distribution

To package the application into a production-ready installer, use the following commands from the root directory:

Command	Platform	Output Artifact
pnpm package:desktop	Current OS	Detects host OS and builds accordingly
pnpm package:mac	macOS	.dmg and .zip (supports x64 & arm64)
pnpm package:win	Windows	.exe (NSIS Installer)
pnpm package:linux	Linux	.AppImage

> **Build Sequence**: All `package:*` commands execute the following pipeline automatically:

1. turbo run build --filter=web — Compiles the React SPA into apps/web/dist/.
2. prebuild hook — Runs node --import tsx scripts/copy-web-dist.ts, which copies apps/web/dist/ → apps/desktop/web-dist/.
3. electron-builder — Bundles web-dist/ into the packaged app via the files and extraResources blocks in electron-builder.yml.

You do not need to run these steps manually — they are chained via npm scripts.

> **macOS Code Signing**: To build a distributable macOS app with Auto-Update support, you **must** have an Apple Developer Certificate and provide `CSC_LINK` and `CSC_KEY_PASSWORD` in your environment. Without code signing, macOS Gatekeeper will block the app and auto-updates will fail. See the Desktop documentation for details.

> **Cross-Compilation**: It is highly recommended to build for Windows on a Windows machine and for macOS on a Mac. Cross-compilation (e.g., building `.dmg` on Linux) may fail due to platform-specific toolchain dependencies. Use a CI matrix strategy (e.g., GitHub Actions with `runs-on: [macos-latest, windows-latest, ubuntu-latest]`) for multi-platform releases.