trackgo-fe/apps/docs-dev/src/setup.md

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

[!NOTE] > 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 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

[!IMPORTANT] > 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.

[!WARNING] > 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.

[!NOTE] > 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.