refactor: migrate docs-dev from storybook to vitepress config and update devcontainer configuration

2026-06-24 13:14:44 +07:00
parent 385452bf36
commit ecb16c759d
26 changed files with 1892 additions and 1414 deletions
@@ -0,0 +1,75 @@
+# Local Development Setup
+
+## 🚀 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**:
+
+```bash
+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.