refactor: Revise configuration and IPC architecture documentation for clarity and security enhancements
- Updated CONFIGURATION.md to reflect changes in target app orchestration, environment variables, and production routing. - Enhanced IPC_ARCHITECTURE.md with a focus on privilege separation, standardized operating procedures, and critical audit checklists. - Added detailed guidelines for extending the IPC bridge and maintaining security integrity. - Introduced new package scripts for macOS, Windows, and Linux builds in package.json.
This commit is contained in:
Firman Ramdhani
@@ -5,15 +5,17 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
A **scalable, enterprise-ready frontend monorepo template** built with **Turborepo**, **pnpm**, and **Vite**.
|
||||
A **scalable, enterprise-ready Web & Desktop monorepo** built with **Turborepo**, **pnpm**, **Vite**, and **Electron**.
|
||||
This repository is designed for long-term maintainability, featuring:
|
||||
|
||||
* Shared logic and UI libraries
|
||||
* Centralized tooling configuration
|
||||
* Turbo-powered task orchestration and caching
|
||||
* Native desktop distribution with auto-updates
|
||||
* Dedicated documentation & component playground using Storybook
|
||||
|
||||
---
|
||||
@@ -26,6 +28,7 @@ The monorepo is organized into **Apps** (deployable applications) and **Packages
|
||||
.
|
||||
├── apps/
|
||||
│ ├── web/ # Main React Application (Vite + TypeScript)
|
||||
│ ├── desktop/ # Electron Desktop Wrapper (electron-vite)
|
||||
│ └── docs-dev/ # Component Documentation & Playground (Storybook)
|
||||
│
|
||||
├── packages/
|
||||
@@ -48,7 +51,7 @@ The monorepo is organized into **Apps** (deployable applications) and **Packages
|
||||
|
||||
Ensure your local environment matches the following versions to avoid compatibility issues:
|
||||
|
||||
* **Node.js**: `v24.11.1`
|
||||
* **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`)
|
||||
|
||||
@@ -68,22 +71,51 @@ This repository uses **Turborepo** to orchestrate tasks efficiently. All command
|
||||
|
||||
### Development
|
||||
|
||||
| Command | Description |
|
||||
| ------------------- | --------------------------------------------------------------------------- |
|
||||
| `pnpm dev` | Start **all applications** (`web` and `docs-dev`) in parallel |
|
||||
| `pnpm dev:web` | Start only the **Main Web App** (usually at `http://localhost:5173`) |
|
||||
| `pnpm dev:docs-dev` | Start **Storybook** for UI development (usually at `http://localhost:6006`) |
|
||||
| Command | Description |
|
||||
| -------------------- | --------------------------------------------------------------------------- |
|
||||
| `pnpm dev` | Start **all applications** (`web` and `docs-dev`) in parallel |
|
||||
| `pnpm dev:web` | Start only the **Main Web App** (usually at `http://localhost:5173`) |
|
||||
| `pnpm dev:docs-dev` | Start **Storybook** for UI development (usually at `http://localhost:6006`) |
|
||||
| `pnpm dev:desktop` | Start the **Web App + Electron** in parallel for desktop development |
|
||||
|
||||
### Building & Quality
|
||||
|
||||
| Command | Description |
|
||||
| --------------------- | --------------------------------------------- |
|
||||
| `pnpm build` | Build all apps and packages using Turbo cache |
|
||||
| `pnpm build:web` | Build only the web application |
|
||||
| `pnpm build:docs-dev` | Build only the docs-dev application |
|
||||
| `pnpm test` | Run unit tests (Vitest) across all packages |
|
||||
| `pnpm lint` | Run ESLint across the workspace |
|
||||
| `pnpm format` | Format code using Prettier |
|
||||
| Command | Description |
|
||||
| --------------------- | ------------------------------------------------------- |
|
||||
| `pnpm build` | Build all apps and packages using Turbo cache |
|
||||
| `pnpm build:web` | Build only the web application |
|
||||
| `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 [AUTO_UPDATER.md](apps/desktop/docs/AUTO_UPDATER.md) 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.
|
||||
|
||||
|
||||
---
|
||||
|
||||
@@ -105,7 +137,42 @@ The main consumer-facing application.
|
||||
|
||||
---
|
||||
|
||||
### 2. `apps/docs-dev` (Storybook)
|
||||
### 2. `apps/desktop`
|
||||
|
||||
The **Electron desktop wrapper** that embeds `apps/web` for native desktop experiences.
|
||||
|
||||
* In **development**: loads the Vite dev server with full hot reload
|
||||
* In **production**: serves the static web build via a secure custom `app://` protocol
|
||||
* Configurable target app via `.env` (can wrap `apps/web`, `apps/docs-dev`, or any future app)
|
||||
|
||||
**Tech Stack**:
|
||||
|
||||
* Electron 33.x
|
||||
* electron-vite
|
||||
* electron-builder
|
||||
* electron-updater
|
||||
|
||||
**Key Capabilities**:
|
||||
|
||||
| Feature | Description |
|
||||
|---|---|
|
||||
| 🖨️ Native Printing | Silent and direct printing via secure IPC bridge |
|
||||
| 🔄 Auto-Updates | Background downloads via GitHub Releases (switchable to S3) |
|
||||
| 🔒 Secure IPC Bridge | `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true` |
|
||||
| 🌐 Custom Protocol | `app://` serves static files with SPA routing fallback to `index.html` |
|
||||
| 🛡️ CORS Bypass | Transparent Origin header rewriting for cloud API calls |
|
||||
|
||||
**Desktop Documentation**:
|
||||
|
||||
| Document | Contents |
|
||||
|---|---|
|
||||
| [CONFIGURATION.md](apps/desktop/docs/CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback |
|
||||
| [AUTO_UPDATER.md](apps/desktop/docs/AUTO_UPDATER.md) | Release workflow, CI/CD variables, provider switching, code signing |
|
||||
| [IPC_ARCHITECTURE.md](apps/desktop/docs/IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, extending native features |
|
||||
|
||||
---
|
||||
|
||||
### 3. `apps/docs-dev` (Storybook)
|
||||
|
||||
An isolated environment for developing and documenting UI components.
|
||||
|
||||
@@ -114,7 +181,7 @@ An isolated environment for developing and documenting UI components.
|
||||
|
||||
---
|
||||
|
||||
### 3. `packages/utils`
|
||||
### 4. `packages/utils`
|
||||
|
||||
Shared business logic and reusable utility modules that can be consumed across multiple applications. Fully tested using Vitest.
|
||||
|
||||
@@ -122,7 +189,7 @@ This package is intended to hold non-UI, cross-cutting logic such as date/time h
|
||||
|
||||
---
|
||||
|
||||
### 4. `packages/ui`
|
||||
### 5. `packages/ui`
|
||||
|
||||
Shared UI component library (Buttons, Inputs, Cards, Layouts).
|
||||
|
||||
@@ -131,7 +198,7 @@ Shared UI component library (Buttons, Inputs, Cards, Layouts).
|
||||
|
||||
---
|
||||
|
||||
### 5. `packages/configs`
|
||||
### 6. `packages/configs`
|
||||
|
||||
Single source of truth for tooling configuration.
|
||||
|
||||
@@ -150,7 +217,7 @@ This repository uses **Turborepo caching** for builds, tests, and other artifact
|
||||
To fully clean the workspace (dependencies, build outputs, and Turbo cache):
|
||||
|
||||
```bash
|
||||
rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist
|
||||
rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist out **/*/out web-dist **/*/web-dist release **/*/release
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user