refactor: migrate docs-dev from storybook to vitepress config and update devcontainer configuration
This commit is contained in:
Firman Ramdhani
@@ -1,38 +0,0 @@
|
||||
import { dirname, join, resolve } from 'path';
|
||||
|
||||
function getAbsolutePath(value) {
|
||||
return dirname(require.resolve(join(value, 'package.json')));
|
||||
}
|
||||
|
||||
const config = {
|
||||
stories: ['../stories/*.stories.tsx', '../stories/**/*.stories.tsx'],
|
||||
addons: [getAbsolutePath('@storybook/addon-links'), getAbsolutePath('@storybook/addon-essentials')],
|
||||
framework: {
|
||||
name: getAbsolutePath('@storybook/react-vite'),
|
||||
options: {},
|
||||
},
|
||||
|
||||
core: {},
|
||||
|
||||
async viteFinal(config, { configType }) {
|
||||
// customize the Vite config here
|
||||
return {
|
||||
...config,
|
||||
define: { 'process.env': {} },
|
||||
resolve: {
|
||||
alias: [
|
||||
{
|
||||
find: 'ui',
|
||||
replacement: resolve(__dirname, '../../../packages/ui/'),
|
||||
},
|
||||
],
|
||||
},
|
||||
};
|
||||
},
|
||||
|
||||
docs: {
|
||||
autodocs: true,
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
+10
-15
@@ -1,33 +1,28 @@
|
||||
{
|
||||
"name": "docs-dev",
|
||||
"name": "@repo/docs-dev",
|
||||
"version": "0.0.0",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"dev": "storybook dev -p 6006",
|
||||
"build": "storybook build --docs",
|
||||
"preview-storybook": "serve storybook-static",
|
||||
"clean": "rm -rf .turbo node_modules",
|
||||
"lint": "eslint ./stories/*.stories.tsx --max-warnings 0"
|
||||
"dev": "vitepress dev src --port 6060",
|
||||
"build": "vitepress build src",
|
||||
"serve": "vitepress serve src --port 6060",
|
||||
"clean": "rm -rf .turbo node_modules src/.vitepress/dist src/.vitepress/cache"
|
||||
},
|
||||
"dependencies": {
|
||||
"@repo/ui": "workspace:*",
|
||||
"dayjs": "^1.11.19",
|
||||
"react": "^19.2.3",
|
||||
"react-dom": "^19.2.3"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@repo/eslint-config": "workspace:*",
|
||||
"@repo/typescript-config": "workspace:*",
|
||||
"@storybook/addon-actions": "^8.2.6",
|
||||
"@storybook/addon-essentials": "^8.2.6",
|
||||
"@storybook/addon-links": "^8.2.6",
|
||||
"@storybook/react": "^8.2.6",
|
||||
"@storybook/react-vite": "^8.2.6",
|
||||
"@vitejs/plugin-react": "^5.1.2",
|
||||
"eslint": "^8.57.0",
|
||||
"serve": "^14.2.1",
|
||||
"storybook": "^8.2.6",
|
||||
"mermaid": "^11.15.0",
|
||||
"typescript": "5.5.4",
|
||||
"vite": "^5.1.4"
|
||||
"vitepress": "^1.6.4",
|
||||
"vitepress-plugin-mermaid": "^2.0.17",
|
||||
"vue": "^3.5.38"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
import { withMermaid } from 'vitepress-plugin-mermaid'
|
||||
|
||||
const config = withMermaid(
|
||||
defineConfig({
|
||||
title: "Frontend Monorepo Docs",
|
||||
description: "Centralized documentation for the Enterprise Frontend Monorepo",
|
||||
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Docs', link: '/overview' },
|
||||
],
|
||||
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Introduction',
|
||||
items: [
|
||||
{ text: 'Overview', link: '/overview' },
|
||||
{ text: 'Local Setup', link: '/setup' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Core Architecture & State',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Core API Engine', link: '/packages/core-api/' },
|
||||
{ text: 'Core Events', link: '/packages/core-events/' },
|
||||
{ text: 'Core Storage', link: '/packages/core-storage/' },
|
||||
{ text: 'Core Internationalization', link: '/packages/core-i18n/' },
|
||||
{ text: 'IPC Architecture', link: '/apps/desktop/IPC_ARCHITECTURE' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'UI System & Layouts',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'UI Components Overview', link: '/packages/ui/' },
|
||||
{ text: 'Core App Shell', link: '/packages/ui/CORE-APP-SHELL' },
|
||||
{ text: 'Form Components', link: '/packages/ui/FORM-COMPONENTS' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'Applications & Configuration',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Desktop Application', link: '/apps/desktop/' },
|
||||
{ text: 'Desktop Configuration', link: '/apps/desktop/CONFIGURATION' },
|
||||
{ text: 'Desktop Auto Updater', link: '/apps/desktop/AUTO_UPDATER' },
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
outline: { level: [2, 3] },
|
||||
socialLinks: [],
|
||||
},
|
||||
|
||||
// Mermaid configuration
|
||||
mermaid: {
|
||||
theme: 'default',
|
||||
},
|
||||
|
||||
// Fix cascading CJS/ESM SyntaxErrors caused by Vite dynamically discovering mermaid
|
||||
vite: {
|
||||
optimizeDeps: {
|
||||
include: [
|
||||
'mermaid'
|
||||
]
|
||||
}
|
||||
}
|
||||
})
|
||||
);
|
||||
|
||||
// Pnpm strict workspace workaround:
|
||||
// vitepress-plugin-mermaid aggressively injects sub-dependencies into optimizeDeps.include.
|
||||
// Because pnpm uses strict symlinks, Vite fails to resolve these sub-dependencies from the project root,
|
||||
// causing pre-bundling to fail and cascading CJS/ESM SyntaxErrors in the browser.
|
||||
// We strip them out so esbuild can naturally inline them into the 'mermaid' chunk instead.
|
||||
if (config.vite?.optimizeDeps?.include) {
|
||||
config.vite.optimizeDeps.include = config.vite.optimizeDeps.include.filter(
|
||||
(dep) => !['@braintree/sanitize-url', 'debug', 'cytoscape-cose-bilkent', 'cytoscape'].includes(dep)
|
||||
);
|
||||
}
|
||||
|
||||
export default config;
|
||||
@@ -0,0 +1,382 @@
|
||||
|
||||
# Desktop Auto-Update System
|
||||
|
||||
`apps/desktop` utilizes a unified update lifecycle powered by **electron-updater**. This architecture ensures seamless, background delivery of application patches, maintaining version parity across our global user base.
|
||||
|
||||
---
|
||||
|
||||
## 🏗 Reactive Update Flow
|
||||
|
||||
The following diagram illustrates the **Reactive Update Flow**, bridging the Node.js Main Process with the React UI layer through a secure IPC event stream.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef coreEntity fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#0f172a
|
||||
classDef ipcBridge fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Subgraphs ───
|
||||
subgraph MainProcess ["Main Process (src/main/index.ts)"]
|
||||
AUTO[autoUpdater.checkForUpdatesAndNotify]
|
||||
EVENTS{{Update Events: progress, downloaded, error}}
|
||||
SENDER[sendToRenderer]
|
||||
end
|
||||
|
||||
subgraph Preload ["IPC Bridge (src/preload/index.ts)"]
|
||||
EXPOSE{contextBridge.exposeInMainWorld}
|
||||
end
|
||||
|
||||
subgraph Renderer ["Renderer (React App - apps/web)"]
|
||||
HOOK([useElectronUpdater Hook])
|
||||
ACTIONS[UI Actions: Install, Check]
|
||||
end
|
||||
|
||||
%% ─── Flow & Relationships ───
|
||||
AUTO ---> EVENTS
|
||||
EVENTS ---> SENDER
|
||||
SENDER ===>|'updater:*' Event Stream| EXPOSE
|
||||
EXPOSE ===>|electronAPI window object| HOOK
|
||||
HOOK -.->|Reactive State Status and Progress| ACTIONS
|
||||
ACTIONS -.->|ipcRenderer.invoke| EXPOSE
|
||||
EXPOSE -.->|Trigger Update or Install| AUTO
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class AUTO,EVENTS,SENDER coreEntity;
|
||||
class EXPOSE ipcBridge;
|
||||
class HOOK,ACTIONS appEntity;
|
||||
|
||||
%% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
|
||||
style MainProcess fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Preload fill:transparent,stroke:#10b981,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Renderer fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
### Lifecycle Sequence
|
||||
|
||||
1. **App launch** → After a 3-second initialization delay, `autoUpdater.checkForUpdatesAndNotify()` is invoked.
|
||||
2. **Update detected** → If `autoDownload` is `true` (default), the binary payload downloads in the background.
|
||||
3. **Progress streaming** → `download-progress` events are forwarded to the renderer via IPC in real-time.
|
||||
4. **Download complete** → The renderer surfaces a "Restart to Update" prompt to the user.
|
||||
5. **User-initiated install** → `autoUpdater.quitAndInstall()` terminates the current process and launches the updated binary.
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Current Provider: GitHub Releases
|
||||
|
||||
The update provider is declared in `electron-builder.yml`:
|
||||
|
||||
```yaml
|
||||
publish:
|
||||
provider: github
|
||||
owner: YOUR_GITHUB_ORG
|
||||
repo: YOUR_REPO_NAME
|
||||
```
|
||||
|
||||
### Operational Mechanics
|
||||
|
||||
1. When `electron-builder --publish always` executes, it:
|
||||
|
||||
- Compiles the application for the target platform.
|
||||
- Uploads the installer(s) to a **GitHub Release** tagged with the version from `package.json`.
|
||||
- Generates and uploads the platform-specific manifest: `latest.yml` (Windows), `latest-mac.yml` (macOS), or `latest-linux.yml` (Linux).
|
||||
|
||||
2. When the packaged application calls `checkForUpdates()`, `electron-updater`:
|
||||
- Reads `app-update.yml` from the app's `resources/` directory (auto-generated during build — never manually created).
|
||||
- Fetches the appropriate `latest*.yml` manifest from the configured release endpoint.
|
||||
- Performs a semantic version comparison and initiates the download if a newer version exists.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Release Workflow: The Deterministic Pipeline
|
||||
|
||||
To maintain release integrity, follow this deterministic pipeline to synchronize web assets and native binaries.
|
||||
|
||||
### Manual Release
|
||||
|
||||
```bash
|
||||
# 1. Version bump — semver discipline
|
||||
cd apps/desktop
|
||||
npm version patch # or: minor, major
|
||||
|
||||
# 2. Compile web assets
|
||||
cd ../..
|
||||
pnpm build --filter=web
|
||||
|
||||
# 3. Synchronize, compile, and publish
|
||||
cd apps/desktop
|
||||
pnpm run prebuild
|
||||
GH_TOKEN=your_token electron-builder --publish always --config electron-builder.yml
|
||||
```
|
||||
|
||||
> [!CAUTION]
|
||||
> **Treat `GH_TOKEN` as a critical secret.** It grants write access to your repository's release assets. Never commit it to version control, never log it in CI output, and always inject it via encrypted secrets or a vault.
|
||||
|
||||
### Automated Release (GitHub Actions)
|
||||
|
||||
```yaml
|
||||
name: Release Desktop
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'desktop-v*'
|
||||
|
||||
jobs:
|
||||
release:
|
||||
strategy:
|
||||
matrix:
|
||||
os: [ubuntu-latest, windows-latest, macos-latest]
|
||||
runs-on: ${{ matrix.os }}
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: pnpm/action-setup@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: pnpm
|
||||
|
||||
- run: pnpm install
|
||||
- run: pnpm build --filter=web
|
||||
- run: cd apps/desktop && pnpm run prebuild
|
||||
- run: cd apps/desktop && pnpm run build
|
||||
|
||||
- name: Publish
|
||||
run: cd apps/desktop && npx electron-builder --publish always --config electron-builder.yml
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GH_TOKEN }}
|
||||
CSC_LINK: ${{ secrets.CSC_LINK }}
|
||||
CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
|
||||
APPLE_ID: ${{ secrets.APPLE_ID }}
|
||||
APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
|
||||
APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 CI/CD Environment Variables
|
||||
|
||||
| Variable | Required | Platform | Description |
|
||||
| ----------------------------- | ------------- | -------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `GH_TOKEN` | Yes | All | GitHub personal access token with `repo` scope. Authorizes release artifact uploads. |
|
||||
| `CSC_LINK` | macOS/Windows | macOS, Windows | Base64-encoded `.p12` code signing certificate. Generate with: `base64 -i cert.p12 \| pbcopy` |
|
||||
| `CSC_KEY_PASSWORD` | macOS/Windows | macOS, Windows | Passphrase for the `.p12` certificate. |
|
||||
| `APPLE_ID` | macOS only | macOS | Apple ID email for notarization submission. |
|
||||
| `APPLE_APP_SPECIFIC_PASSWORD` | macOS only | macOS | App-specific password generated at [appleid.apple.com](https://appleid.apple.com). |
|
||||
| `APPLE_TEAM_ID` | macOS only | macOS | Your Apple Developer Team ID. |
|
||||
| `WIN_CSC_LINK` | Windows only | Windows | Separate Windows code signing certificate (if different from `CSC_LINK`). |
|
||||
| `WIN_CSC_KEY_PASSWORD` | Windows only | Windows | Passphrase for the Windows certificate. |
|
||||
|
||||
### Configuring Secrets
|
||||
|
||||
1. Navigate to **Settings → Secrets and variables → Actions** in your GitHub repository.
|
||||
2. Add each variable as a **Repository secret**.
|
||||
3. Reference them in workflow files as <code v-pre>${{ secrets.VARIABLE_NAME }}</code>.
|
||||
|
||||
---
|
||||
|
||||
## ☁️ Deployment Strategies
|
||||
|
||||
### AWS S3 (Private Infrastructure)
|
||||
|
||||
For enterprise environments requiring private infrastructure, the system can be reconfigured to target an **AWS S3 Bucket** or a **CloudFront Distribution**.
|
||||
|
||||
Update `electron-builder.yml`:
|
||||
|
||||
```yaml
|
||||
publish:
|
||||
provider: s3
|
||||
bucket: your-bucket-name
|
||||
region: ap-southeast-1
|
||||
path: /desktop-releases
|
||||
acl: private
|
||||
```
|
||||
|
||||
**Additional environment variables:**
|
||||
|
||||
| Variable | Description |
|
||||
| ----------------------- | -------------------------------------------------------------- |
|
||||
| `AWS_ACCESS_KEY_ID` | IAM access key with S3 `PutObject` and `GetObject` permissions |
|
||||
| `AWS_SECRET_ACCESS_KEY` | IAM secret key |
|
||||
|
||||
**Bucket structure:**
|
||||
|
||||
```text
|
||||
your-bucket/desktop-releases/
|
||||
├── latest.yml (Windows manifest)
|
||||
├── latest-mac.yml (macOS manifest)
|
||||
├── latest-linux.yml (Linux manifest)
|
||||
├── EigenDesktop-Setup-0.2.0.exe
|
||||
├── EigenDesktop-0.2.0.dmg
|
||||
├── EigenDesktop-0.2.0-mac.zip
|
||||
└── EigenDesktop-0.2.0.AppImage
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> The bucket must allow public read access to the manifest files (`latest*.yml`), or you must configure a CloudFront distribution. `electron-updater` performs unauthenticated `GET` requests to resolve the latest version.
|
||||
|
||||
### Generic File Server (Self-Hosted)
|
||||
|
||||
For self-hosted infrastructure (Nginx, Caddy, etc.):
|
||||
|
||||
```yaml
|
||||
publish:
|
||||
provider: generic
|
||||
url: [https://updates.your-domain.com/desktop](https://updates.your-domain.com/desktop)
|
||||
```
|
||||
|
||||
Your server must host the same directory structure as the S3 layout above.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **MIME Type Configuration**: Ensure your file server correctly serves `.yml` files with `text/yaml` and installer binaries with `application/octet-stream`. Incorrect MIME types will cause download corruption or silent update failures.
|
||||
|
||||
**Nginx reference:**
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name updates.your-domain.com;
|
||||
|
||||
location /desktop/ {
|
||||
alias /var/www/desktop-releases/;
|
||||
autoindex off;
|
||||
add_header Cache-Control "no-cache";
|
||||
|
||||
# MIME types for update manifests
|
||||
types {
|
||||
text/yaml yml;
|
||||
application/octet-stream exe dmg AppImage zip;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Code Signing: The Trust Boundary
|
||||
|
||||
> [!WARNING]
|
||||
> **Code signing is not merely a requirement — it is the Trust Boundary established by the operating system.** macOS Gatekeeper will explicitly terminate unsigned applications or refuse background updates to maintain system integrity. Windows SmartScreen will display alarming warnings to users. Without valid signatures, `electron-updater` will **reject update payloads entirely**.
|
||||
|
||||
### macOS
|
||||
|
||||
- Requires an **Apple Developer ID Application** certificate ($99/year Apple Developer Program).
|
||||
- The `electron-builder.yml` is configured with:
|
||||
```yaml
|
||||
mac:
|
||||
hardenedRuntime: true
|
||||
gatekeeperAssess: false
|
||||
entitlements: build/entitlements.mac.plist
|
||||
entitlementsInherit: build/entitlements.mac.plist
|
||||
```
|
||||
- You must create `apps/desktop/build/entitlements.mac.plist`:
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
||||
"[http://www.apple.com/DTDs/PropertyList-1.0.dtd](http://www.apple.com/DTDs/PropertyList-1.0.dtd)">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>com.apple.security.cs.allow-jit</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
|
||||
<true/>
|
||||
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
|
||||
<true/>
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
- **Notarization** is mandatory for macOS 10.15+. Provide `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, and `APPLE_TEAM_ID`.
|
||||
|
||||
### Windows
|
||||
|
||||
- Requires an **EV Code Signing Certificate** or a standard code signing certificate from a trusted CA.
|
||||
- Without signing, Windows SmartScreen warns users with "Windows protected your PC" — severely impacting adoption.
|
||||
- **EV certificates** eliminate SmartScreen warnings immediately; standard certificates build trust reputation over time through Microsoft's telemetry.
|
||||
|
||||
### Linux
|
||||
|
||||
- Code signing is **not enforced** by the OS for AppImage distribution.
|
||||
- Optional GPG signing is available for package managers that support it.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Updates in Development
|
||||
|
||||
> [!NOTE]
|
||||
> The auto-updater is **intentionally disabled** in development mode to prevent runtime crashes. Setting `forceDevUpdateConfig` requires a `dev-app-update.yml` file, which introduces unnecessary complexity during local development.
|
||||
|
||||
### What Happens in Dev Mode
|
||||
|
||||
In `src/main/index.ts`, the `setupAutoUpdaterEvents()` function detects `IS_DEV` and returns early:
|
||||
|
||||
```typescript
|
||||
if (IS_DEV) {
|
||||
autoUpdater.autoDownload = false;
|
||||
return; // Skip event registration — no update server in dev
|
||||
}
|
||||
```
|
||||
|
||||
This means:
|
||||
|
||||
- No update check is performed on startup.
|
||||
- No `electron-updater` events are emitted.
|
||||
- The `useElectronUpdater()` hook will remain in `idle` status.
|
||||
|
||||
### How to Test Updates
|
||||
|
||||
Auto-update can **only** be fully validated using a **packaged, signed build** distributed through a real update channel:
|
||||
|
||||
1. **Publish v0.1.0** → Package and release a signed build.
|
||||
2. **Bump to v0.2.0** → Increment the version in `package.json`.
|
||||
3. **Publish v0.2.0** → Package and release the updated build.
|
||||
4. **Launch v0.1.0** → The app should detect v0.2.0, download it, and prompt the user to restart.
|
||||
|
||||
For rapid iteration, use the `generic` provider pointing to a local Nginx or Python HTTP server:
|
||||
|
||||
```yaml
|
||||
# electron-builder.yml (temporary, for testing)
|
||||
publish:
|
||||
provider: generic
|
||||
url: http://localhost:8080/updates
|
||||
```
|
||||
|
||||
```bash
|
||||
# Serve the release directory locally
|
||||
cd apps/desktop/release
|
||||
python3 -m http.server 8080 --directory .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Diagnostic Runbook
|
||||
|
||||
### Issue: "Update check failed" on startup
|
||||
|
||||
| Symptom | Root Cause | Resolution |
|
||||
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Console logs `[AutoUpdater] Startup check failed (possibly offline)` | The machine is offline, or the update server (GitHub/S3/generic) is unreachable. | No action required. The error is caught in a `try/catch` block, logged to the console, and the application continues to function normally. The next check will occur on the next app launch. |
|
||||
|
||||
### Issue: `app-update.yml` not found in production build
|
||||
|
||||
| Symptom | Root Cause | Resolution |
|
||||
| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `electron-updater` throws "Cannot find app-update.yml" immediately after launch. | The `publish` block in `electron-builder.yml` is missing or misconfigured. `electron-builder` generates `app-update.yml` only when a valid provider is declared. | Verify the `publish` block exists in `electron-builder.yml`. Run `electron-builder --publish never` and inspect `release/*/resources/app-update.yml` to confirm generation. |
|
||||
|
||||
### Issue: "Cannot update: code signature is invalid" (macOS)
|
||||
|
||||
| Symptom | Root Cause | Resolution |
|
||||
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| The updater downloads a new version but refuses to apply it, logging a signature validation error. | The application was not signed, or the signing certificate has expired / been revoked. | Ensure `CSC_LINK` and `CSC_KEY_PASSWORD` are correctly set in CI. Verify the packaged app with: `codesign --verify --deep --strict release/mac*/Desktop.app`. Re-sign and re-publish if the certificate was rotated. |
|
||||
|
||||
### Issue: Updates work on Windows/Linux but not macOS
|
||||
|
||||
| Symptom | Root Cause | Resolution |
|
||||
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Windows and Linux users receive updates, but macOS users see no update prompt. | macOS requires **both** a valid code signature AND Apple notarization. Without notarization, Gatekeeper silently quarantines the update payload. | Provide all Apple credential environment variables (`APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`) and ensure `hardenedRuntime: true` is set in `electron-builder.yml`. Re-package and re-publish. |
|
||||
|
||||
### Issue: S3/Generic provider returns corrupted downloads
|
||||
|
||||
| Symptom | Root Cause | Resolution |
|
||||
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Users report that the update downloads but fails to install, or the downloaded file is 0 bytes. | The file server is serving update manifests or binaries with incorrect MIME types, or a CDN is caching stale `latest*.yml` files. | Verify MIME types: `.yml` → `text/yaml`, `.exe`/`.dmg`/`.AppImage`/`.zip` → `application/octet-stream`. Add `Cache-Control: no-cache` headers to `latest*.yml` responses. Invalidate CDN cache after publishing a new release. |
|
||||
@@ -0,0 +1,281 @@
|
||||
|
||||
# Desktop Configuration Guide
|
||||
|
||||
The Blueprint for Runtime Control.
|
||||
|
||||
> This guide defines the operational parameters of the Desktop Wrapper. It governs the orchestration of target applications, encapsulates the mechanics of our proprietary production routing, and provides a fail-safe **Break Glass Procedure** for emergency infrastructure transitions.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Target App Orchestration](#target-app-orchestration)
|
||||
- [Environment Variables Registry](#environment-variables-registry)
|
||||
- [Deterministic Path Resolution](#deterministic-path-resolution)
|
||||
- [Production Routing: Overcoming Protocol Constraints](#production-routing-overcoming-protocol-constraints)
|
||||
- [Defense-in-Depth: Multi-Layered Protection](#defense-in-depth-multi-layered-protection)
|
||||
- [Break Glass Procedure: Disaster Recovery Protocol](#break-glass-procedure-disaster-recovery-protocol)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Target App Orchestration
|
||||
|
||||
The Desktop Wrapper is architected to embed **any** web application within the monorepo ecosystem. The target application is resolved at build time through a declarative configuration surface in `apps/desktop/.env`.
|
||||
|
||||
### `.env` Declaration
|
||||
|
||||
```env
|
||||
# The workspace identifier of the target web application.
|
||||
# Must correspond to a directory under apps/ (e.g., "web", "docs-dev", "admin").
|
||||
DESKTOP_TARGET_APP=web
|
||||
|
||||
# The Vite development server endpoint for the target application.
|
||||
DESKTOP_DEV_SERVER_URL=http://localhost:5173
|
||||
```
|
||||
|
||||
### Switching the Target Application
|
||||
|
||||
To redirect the wrapper to a different application — for example, `apps/admin` — modify the configuration and re-execute the build pipeline:
|
||||
|
||||
1. **Update the `.env` declaration:**
|
||||
|
||||
```env
|
||||
DESKTOP_TARGET_APP=admin
|
||||
DESKTOP_DEV_SERVER_URL=http://localhost:3001
|
||||
```
|
||||
|
||||
2. **Verify the target app exports a `build` script** that emits static assets to `dist/`.
|
||||
|
||||
3. **Execute the deterministic build pipeline:**
|
||||
```bash
|
||||
pnpm build --filter=admin && cd apps/desktop && pnpm run build
|
||||
```
|
||||
|
||||
### The Deployment Bridge
|
||||
|
||||
The `prebuild` hook invokes `scripts/copy-web-dist.ts`, which serves as the **Deployment Bridge** between the web workspace and the native container. It reads `DESKTOP_TARGET_APP`, resolves the corresponding `apps/<target>/dist/` directory, and synchronizes the contents into `apps/desktop/web-dist/`. This bridge directory is then ingested by `electron-builder`.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef webApp fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef bridge fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
classDef electronApp fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#0f172a
|
||||
classDef finalArtifact fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Nodes ───
|
||||
SOURCE[(apps/TARGET/dist/)]
|
||||
SCRIPT{copy-web-dist.ts}
|
||||
DEST[(apps/desktop/web-dist/)]
|
||||
BUILDER(electron-builder)
|
||||
OUTPUT([Packaged .app / .exe])
|
||||
|
||||
%% ─── Flow ───
|
||||
SOURCE ===>|Vite Build Output| SCRIPT
|
||||
SCRIPT ===>|Deployment Bridge Prebuild Hook| DEST
|
||||
DEST -.->|files and extraResources| BUILDER
|
||||
BUILDER ===> OUTPUT
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class SOURCE webApp;
|
||||
class SCRIPT bridge;
|
||||
class DEST,BUILDER electronApp;
|
||||
class OUTPUT finalArtifact;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Environment Variables Registry
|
||||
|
||||
| Variable | Default | Security Scope | Consumer | Description |
|
||||
| ----------------------------- | ----------------------- | -------------- | ------------------- | --------------------------------------------------------------- |
|
||||
| `DESKTOP_TARGET_APP` | `web` | Build-time | `copy-web-dist.ts` | Workspace identifier of the web app to embed |
|
||||
| `DESKTOP_DEV_SERVER_URL` | `http://localhost:5173` | Runtime (dev) | `src/main/index.ts` | Dev server URL loaded in the Electron window during development |
|
||||
| `GH_TOKEN` | — | CI/CD | `electron-builder` | GitHub personal access token for publishing releases |
|
||||
| `CSC_LINK` | — | CI/CD | `electron-builder` | Base64-encoded `.p12` code signing certificate |
|
||||
| `CSC_KEY_PASSWORD` | — | CI/CD | `electron-builder` | Passphrase for the `.p12` certificate |
|
||||
| `APPLE_ID` | — | CI/CD (macOS) | `electron-builder` | Apple ID email for notarization submission |
|
||||
| `APPLE_APP_SPECIFIC_PASSWORD` | — | CI/CD (macOS) | `electron-builder` | App-specific password for notarization |
|
||||
| `APPLE_TEAM_ID` | — | CI/CD (macOS) | `electron-builder` | Apple Developer Team ID |
|
||||
|
||||
> [!IMPORTANT] > **Build-time** variables are consumed during the `prebuild` phase and baked into the artifact. **Runtime** variables are read by the Electron main process at launch. **CI/CD** variables are secrets injected exclusively in the deployment environment — they must never appear in source control or local `.env` files.
|
||||
|
||||
---
|
||||
|
||||
## 📂 Deterministic Path Resolution
|
||||
|
||||
The following matrix defines how the target app's static assets are resolved across every phase of the application lifecycle. Each path is **deterministic** — there is no runtime ambiguity.
|
||||
|
||||
| Phase | Resolution Strategy | Resolved Path | Context |
|
||||
| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- |
|
||||
| **Prebuild** | `copy-web-dist.ts` reads `DESKTOP_TARGET_APP` | `monorepo-root/apps/<target>/dist/` → `apps/desktop/web-dist/` | Deployment Bridge: build-time synchronization |
|
||||
| **Development** | `__dirname` relative traversal from `out/main/` | `apps/desktop/out/main/` → `../../` → `apps/` → `<target>/dist/` | Direct filesystem access to the web app's build output |
|
||||
| **Production** | `process.resourcesPath` | `Contents/Resources/web-dist/` (macOS) / `resources/web-dist/` (Windows/Linux) | OS-specific resource directory within the packaged binary |
|
||||
|
||||
> [!NOTE]
|
||||
> The development path relies on `__dirname` pointing to `apps/desktop/out/main/` at runtime. If electron-vite's output directory is ever reconfigured, this traversal must be updated in `getWebDistPath()` within `src/main/index.ts`.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Production Routing: Overcoming Protocol Constraints
|
||||
|
||||
### The Constraint
|
||||
|
||||
React applications using `BrowserRouter` rely on a fundamental server-side contract: **every URL path must return `index.html`**. Paths like `/dashboard`, `/auth/login`, and `/settings/profile` do not correspond to physical files — they are virtual routes resolved entirely by the client-side router.
|
||||
|
||||
Electron's default `file://` protocol breaks this contract. Requesting `file:///app/dashboard` triggers a literal filesystem lookup for a file named `dashboard`, which does not exist, resulting in a blank screen or an OS-level "file not found" error.
|
||||
|
||||
### The Solution: A Privileged Virtual File System
|
||||
|
||||
The `app://` scheme is a **Privileged Virtual File System** that resolves SPA routing conflicts by implementing a **Heuristic Resource Loader**. It operates as follows:
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions ───
|
||||
classDef request fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
|
||||
classDef process fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#0f172a
|
||||
classDef decision fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
classDef success fill:#3b82f6,stroke:#1d4ed8,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Nodes ───
|
||||
REQ([Request: app://-/settings/profile])
|
||||
DECODE[Decode URI and Normalize Path]
|
||||
CHECK{File exists in web-dist?}
|
||||
SERVE_FILE[Serve Asset with MIME + CSP]
|
||||
SERVE_FALLBACK[Heuristic Fallback: Serve index.html]
|
||||
REACT([React Router Handles Route])
|
||||
|
||||
%% ─── Flow ───
|
||||
REQ ---> DECODE
|
||||
DECODE ---> CHECK
|
||||
CHECK ===>|YES| SERVE_FILE
|
||||
CHECK -.->|NO| SERVE_FALLBACK
|
||||
SERVE_FALLBACK ---> REACT
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class REQ request;
|
||||
class DECODE process;
|
||||
class CHECK decision;
|
||||
class SERVE_FILE,SERVE_FALLBACK,REACT success;
|
||||
```
|
||||
|
||||
If a requested URI does not map to a physical asset, the handler intelligently intercepts the request to serve the `index.html` entry point, allowing React Router to maintain stateful client-side navigation. This ensures that deep links, page refreshes, and direct URL entry all function without modification to the React app's routing configuration.
|
||||
|
||||
### Scheme Registration
|
||||
|
||||
The scheme **must** be registered synchronously at module load time, before `app.whenReady()`. This is a Chromium requirement — deferred registration will silently fail:
|
||||
|
||||
```typescript
|
||||
protocol.registerSchemesAsPrivileged([
|
||||
{
|
||||
scheme: 'app',
|
||||
privileges: {
|
||||
standard: true, // Enables URL parsing (host, path, query)
|
||||
secure: true, // Treated as a secure origin (HTTPS equivalent)
|
||||
supportFetchAPI: true, // Allows fetch() from this scheme
|
||||
corsEnabled: true, // Enables CORS for cross-origin requests
|
||||
stream: true, // Supports streaming responses
|
||||
},
|
||||
},
|
||||
]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Defense-in-Depth: Multi-Layered Protection
|
||||
|
||||
The custom protocol handler enforces a **multi-layered defense perimeter** that goes beyond standard Electron security defaults.
|
||||
|
||||
| Layer | Technique | Implementation | Threat Mitigated |
|
||||
| ------------------------------ | ------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
|
||||
| **I/O Sanitization** | Path traversal guard | `normalize()` + `startsWith()` validation against `web-dist/` boundary | Directory traversal attacks (`../../etc/passwd`) → `403 Forbidden` |
|
||||
| **In-Flight Policy Injection** | CSP response headers | `Content-Security-Policy` injected as HTTP response headers on every HTML payload | XSS execution via script injection |
|
||||
| **Cryptographic Isolation** | Privileged scheme registration | `app` scheme registered with `standard`, `secure`, `supportFetchAPI`, `corsEnabled` | Scheme downgrade attacks; the renderer treats `app://` identically to `https://` |
|
||||
| **Resource Type Validation** | `statSync.isFile()` check | Only regular files are served; directories return the SPA fallback | Information disclosure via directory listing |
|
||||
| **Origin Sanitization** | CORS bypass proxy | `webRequest.onBeforeSendHeaders` strips `app://` Origin headers on outgoing requests | Backend CORS rejection of non-standard origins |
|
||||
| **Navigation Confinement** | `will-navigate` guard | Blocks navigation to URLs outside `app://` and the authorized dev server | Phishing via in-app redirect to malicious sites |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Break Glass Procedure: Disaster Recovery Protocol
|
||||
|
||||
> [!CAUTION] > **This is a formal Disaster Recovery Protocol.** Execute only if the custom `app://` protocol causes an irrecoverable failure — for example, a critical third-party library that refuses to operate under a non-standard URI scheme. This procedure requires coordinated changes across both the React application and the Electron main process. Estimated recovery time: **15 minutes**.
|
||||
|
||||
### Step 1: Switch the Router — React Application
|
||||
|
||||
In the target web app's entry point (e.g., `apps/web/src/apps/index.tsx`):
|
||||
|
||||
```diff
|
||||
- import { BrowserRouter, Navigate, Route, Routes } from 'react-router-dom';
|
||||
+ import { HashRouter, Navigate, Route, Routes } from 'react-router-dom';
|
||||
|
||||
export default function App() {
|
||||
return (
|
||||
<ThemeProvider colorScheme={colorScheme} density={density}>
|
||||
- <BrowserRouter>
|
||||
+ <HashRouter>
|
||||
<Suspense fallback={<div>Loading...</div>}>
|
||||
<Routes>
|
||||
{/* All route definitions remain unchanged */}
|
||||
</Routes>
|
||||
</Suspense>
|
||||
- </BrowserRouter>
|
||||
+ </HashRouter>
|
||||
</ThemeProvider>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
All routes transition to hash-based addressing: `#/app/dashboard`, `#/auth/login`, `#/showcase`.
|
||||
|
||||
### Step 2: Decommission the Custom Protocol — Main Process
|
||||
|
||||
In `apps/desktop/src/main/index.ts`, execute the following surgical removals:
|
||||
|
||||
**a)** Remove the scheme registration block at the top of the file:
|
||||
|
||||
```diff
|
||||
- protocol.registerSchemesAsPrivileged([ ... ]);
|
||||
```
|
||||
|
||||
**b)** Delete the entire `registerAppProtocol()` function.
|
||||
|
||||
**c)** Remove the `registerAppProtocol()` invocation inside `app.whenReady()`.
|
||||
|
||||
**d)** Redirect production content loading in `createWindow()`:
|
||||
|
||||
```diff
|
||||
if (IS_DEV) {
|
||||
mainWindow.loadURL(DEV_SERVER_URL);
|
||||
mainWindow.webContents.openDevTools({ mode: 'detach' });
|
||||
} else {
|
||||
- mainWindow.loadURL('app://-/index.html');
|
||||
+ const webDistPath = getWebDistPath();
|
||||
+ mainWindow.loadFile(join(webDistPath, 'index.html'));
|
||||
}
|
||||
```
|
||||
|
||||
**e)** Inject a CSP `<meta>` tag into the web app's `index.html`, since the In-Flight Policy Injection layer is no longer available:
|
||||
|
||||
```html
|
||||
<meta
|
||||
http-equiv="Content-Security-Policy"
|
||||
content="default-src 'self' file:; script-src 'self' file:;
|
||||
style-src 'self' 'unsafe-inline' file:;
|
||||
connect-src 'self' https:;
|
||||
img-src 'self' file: data: https:;
|
||||
font-src 'self' file: data:;"
|
||||
/>
|
||||
```
|
||||
|
||||
### Trade-off Analysis
|
||||
|
||||
| Dimension | Custom `app://` Protocol | `file://` + HashRouter |
|
||||
| --------------------------------- | -------------------------------------------------- | ----------------------------------------------------------- |
|
||||
| **Aesthetic Integrity** | Clean URLs: `/app/dashboard` | Hash prefix: `#/app/dashboard` |
|
||||
| **Router Compatibility** | `BrowserRouter` — zero changes required | Must migrate to `HashRouter` |
|
||||
| **Deep Linking** | Full, native-style support | Hash-based only |
|
||||
| **Protocol-Native Compatibility** | Rare edge cases with non-standard scheme detection | Maximum third-party compatibility |
|
||||
| **Security Delivery Vector** | CSP via response headers (strongest enforcement) | CSP via `<meta>` tag (bypassable by early script execution) |
|
||||
| **Implementation Complexity** | Higher (custom protocol handler + security layers) | Lower (no custom protocol infrastructure) |
|
||||
| **Recovery Time** | — | ~15 minutes, 2 files |
|
||||
@@ -0,0 +1,447 @@
|
||||
---
|
||||
outline: [2, 3]
|
||||
---
|
||||
|
||||
# IPC Architecture & Security Model
|
||||
|
||||
> **Scope**: Electron Main ↔ Renderer process communication
|
||||
> **Enforcement Level**: Mandatory — deviations constitute security violations
|
||||
|
||||
This document defines the **hardened security perimeter** and communication topology governing the Desktop Wrapper. Every native capability exposed to the Renderer is mediated through a **non-bypassable IPC bridge**, enforcing strict privilege separation between the Node.js Main Process and untrusted web content.
|
||||
|
||||
The architecture operates on three invariants:
|
||||
|
||||
| Invariant | Guarantee |
|
||||
|---|---|
|
||||
| **Context Encapsulation** | The Preload Script executes in a hermetically sealed V8 context, isolated from both Main Process globals and the Renderer DOM. |
|
||||
| **Interface Narrowing** | Only explicitly declared, type-safe API surfaces are exposed via `contextBridge`. No wildcard access patterns exist. |
|
||||
| **Deterministic Lifecycle** | All IPC subscriptions are paired with unsubscribe functions, tying native event listeners to React's component lifecycle to prevent memory leaks. |
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Privilege Separation Model](#privilege-separation-model)
|
||||
- [Standard Operating Procedure: The Three-Step Bridge](#standard-operating-procedure-the-three-step-bridge)
|
||||
- [Verified Channel Manifest](#verified-channel-manifest)
|
||||
- [Extending the Bridge: Guided Walkthrough](#extending-the-bridge-guided-walkthrough)
|
||||
- [Critical Audit Checklist: Anti-Patterns](#critical-audit-checklist-anti-patterns)
|
||||
- [The Gold Standard for Native Integration](#the-gold-standard-for-native-integration)
|
||||
|
||||
---
|
||||
|
||||
## Privilege Separation Model
|
||||
|
||||
The desktop wrapper enforces a **strict privilege separation** between three execution contexts, each operating under fundamentally different trust levels. This architecture ensures that a compromise in any single layer cannot escalate to full system access.
|
||||
|
||||
### Trust Level Matrix
|
||||
|
||||
| Context | Trust Level | Privilege Scope | Security Guarantee |
|
||||
| ------------------ | ------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| **Main Process** | Fully Trusted | Unrestricted Node.js access: filesystem, network, printers, OS APIs, child processes | Only code authored by the engineering team executes here |
|
||||
| **Preload Script** | Controlled | Restricted to `ipcRenderer.invoke()` and `ipcRenderer.send()` — no direct Node.js access | Executes in a **Hermetically Sealed Context** — isolated from both the Main Process globals and the Renderer's DOM |
|
||||
| **Renderer** | Untrusted | Standard browser sandbox — zero Node.js API surface | Designated as a **Zero-Trust Environment** — may execute third-party code, npm packages, or XSS payloads |
|
||||
|
||||
### Process Topology
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef trustedLayer fill:#f8fafc,stroke:#3b82f6,stroke-width:2px,color:#0f172a
|
||||
classDef gatewayLayer fill:#f0fdf4,stroke:#10b981,stroke-width:2px,color:#064e3b
|
||||
classDef untrustedLayer fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#7f1d1d
|
||||
classDef functionNode fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#0f172a
|
||||
|
||||
%% ─── Subgraphs ───
|
||||
subgraph Main ["MAIN PROCESS [Fully Trusted]"]
|
||||
M_DESC["Unrestricted Node.js Privileges"]
|
||||
IPC_MAIN_H[ipcMain.handle]
|
||||
IPC_MAIN_O[ipcMain.on]
|
||||
end
|
||||
|
||||
subgraph Preload ["PRELOAD SCRIPT [Secure Gateway]"]
|
||||
P_DESC["Hermetically Sealed Context (Interface Narrowing)"]
|
||||
CTX_BRIDGE{contextBridge.exposeInMainWorld}
|
||||
end
|
||||
|
||||
subgraph Renderer ["RENDERER [Zero-Trust Environment]"]
|
||||
R_DESC["Standard Browser Sandbox (No Node.js APIs)"]
|
||||
E_API([window.electronAPI])
|
||||
end
|
||||
|
||||
%% ─── Flow & Relationships ───
|
||||
E_API ===>|Only Authorized Vector| CTX_BRIDGE
|
||||
CTX_BRIDGE --->|Transforms to narrow IPC calls| IPC_MAIN_H
|
||||
CTX_BRIDGE --->|Transforms to narrow IPC calls| IPC_MAIN_O
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class Main trustedLayer;
|
||||
class Preload gatewayLayer;
|
||||
class Renderer untrustedLayer;
|
||||
class M_DESC,P_DESC,R_DESC,IPC_MAIN_H,IPC_MAIN_O functionNode;
|
||||
class CTX_BRIDGE gatewayLayer;
|
||||
class E_API untrustedLayer;
|
||||
|
||||
%% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
|
||||
style Main fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Preload fill:transparent,stroke:#10b981,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Renderer fill:transparent,stroke:#ef4444,stroke-width:2px,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
The Preload Script functions as a **Secure Gateway** that performs **Interface Narrowing** — it transforms the broad, unrestricted IPC capabilities of the Main Process into a deliberately narrow, type-safe API surface. The renderer communicates with native functionality **exclusively** through this gateway. There are no alternative paths, no escape hatches, and no backdoors.
|
||||
|
||||
### Enforcement Configuration
|
||||
|
||||
These settings are declared in `BrowserWindow.webPreferences` and are **non-negotiable**:
|
||||
|
||||
| Setting | Value | Enforcement |
|
||||
| ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `contextIsolation` | `true` | The Preload executes in a hermetically sealed V8 context. The renderer **cannot** access `require()`, Node.js globals, or any variable from the preload's scope. |
|
||||
| `nodeIntegration` | `false` | **Zero** Node.js API surface in the renderer. `fs`, `child_process`, `os`, `net`, and all built-in modules are completely unavailable. |
|
||||
| `sandbox` | `true` | The renderer process runs inside a **Chromium OS-level sandbox**, restricting system calls and file access at the kernel level. |
|
||||
| `webSecurity` | `true` | The same-origin policy is **strictly enforced**, preventing cross-origin data exfiltration from the renderer. |
|
||||
|
||||
---
|
||||
|
||||
## Standard Operating Procedure: The Three-Step Bridge
|
||||
|
||||
Every native feature in this architecture **must** follow the Three-Step Bridge — a Standard Operating Procedure (SOP) that ensures traceability, type-safety, and auditability across the entire IPC surface.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Deterministic Synchronization**: Maintaining parity between the Main Process handler, the Preload Gateway exposure, and the TypeScript interface declaration is **mandatory**. A mismatch between any two of the three layers will result in either a **Type-Safety Gap** (silent failures in development) or a **Runtime Regression** (crashes in production).
|
||||
|
||||
### Step 1: Register the Handler — Main Process
|
||||
|
||||
**File:** `apps/desktop/src/main/index.ts`
|
||||
|
||||
```typescript
|
||||
// COMMAND PATTERN: Use ipcMain.handle for request/response operations
|
||||
// The handler returns a value to the renderer via a resolved Promise.
|
||||
ipcMain.handle('feature:action', async (_event, arg1: string, arg2: number) => {
|
||||
// Validate inputs. Never trust data from the renderer.
|
||||
if (typeof arg1 !== 'string' || typeof arg2 !== 'number') {
|
||||
throw new Error('Invalid arguments');
|
||||
}
|
||||
const result = await someNativeAPI(arg1, arg2);
|
||||
return result;
|
||||
});
|
||||
|
||||
// EVENT PATTERN: Use ipcMain.on for fire-and-forget operations
|
||||
// No return value — the renderer does not wait for a response.
|
||||
ipcMain.on('feature:fire', (_event, data: SomeType) => {
|
||||
performSideEffect(data);
|
||||
});
|
||||
```
|
||||
|
||||
**Channel naming convention:** `namespace:action` — examples: `printer:get-list`, `updater:check`, `app:get-version`. Namespaces must be unique, descriptive, and never generic.
|
||||
|
||||
### Step 2: Expose via contextBridge — Preload Gateway
|
||||
|
||||
**File:** `apps/desktop/src/preload/index.ts`
|
||||
|
||||
```typescript
|
||||
const electronAPI = {
|
||||
// Command pattern exposure
|
||||
featureAction: (arg1: string, arg2: number): Promise<ResultType> => {
|
||||
return ipcRenderer.invoke('feature:action', arg1, arg2);
|
||||
},
|
||||
|
||||
// Event pattern exposure
|
||||
featureFire: (data: SomeType): void => {
|
||||
ipcRenderer.send('feature:fire', data);
|
||||
},
|
||||
|
||||
// Main→Renderer push events (with automatic lifecycle cleanup)
|
||||
onFeatureEvent: createEventSubscription<EventDataType>('feature:event'),
|
||||
};
|
||||
|
||||
contextBridge.exposeInMainWorld('electronAPI', electronAPI);
|
||||
```
|
||||
|
||||
**Non-negotiable rules:**
|
||||
|
||||
- **Never** expose `ipcRenderer` directly — this is a **Catastrophic Failure** pattern.
|
||||
- **Never** expose `ipcRenderer.on` without cleanup — use `createEventSubscription()`, which returns an unsubscribe function for React `useEffect` lifecycle management.
|
||||
- **Always** declare explicit TypeScript types for all function signatures.
|
||||
|
||||
### Step 3: Declare the Interface — React Application
|
||||
|
||||
**File:** `apps/web/src/types/electron.d.ts`
|
||||
|
||||
```typescript
|
||||
interface ElectronAPI {
|
||||
// ... existing methods ...
|
||||
|
||||
featureAction: (arg1: string, arg2: number) => Promise<ResultType>;
|
||||
featureFire: (data: SomeType) => void;
|
||||
onFeatureEvent: (callback: (data: EventDataType) => void) => () => void;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verified Channel Manifest
|
||||
|
||||
The following is the **complete, authoritative registry** of all authorized IPC channels. These channels are the **only** permitted vectors for native interaction. Any IPC channel not listed here is unauthorized and must be treated as a security anomaly.
|
||||
|
||||
### Printer Subsystem
|
||||
|
||||
| Channel | Direction | Pattern | Payload | Access Control |
|
||||
| ------------------ | -------------------------- | ------------------- | --------------------------------------------------------------------- | ------------------------------ |
|
||||
| `printer:get-list` | Renderer → Main → Renderer | `invoke` / `handle` | Returns `ElectronPrinterInfo[]` | Read-only hardware enumeration |
|
||||
| `printer:print` | Renderer → Main → Renderer | `invoke` / `handle` | Accepts `ElectronPrintOptions`, returns `{ success, failureReason? }` | Controlled hardware invocation |
|
||||
|
||||
**Main process handler:** `setupPrinterIPC()` in `src/main/index.ts`
|
||||
|
||||
**Preload Gateway surface:**
|
||||
|
||||
```typescript
|
||||
getPrinters: () => ipcRenderer.invoke('printer:get-list');
|
||||
print: (options?) => ipcRenderer.invoke('printer:print', options);
|
||||
```
|
||||
|
||||
**React consumption hook:** `useElectronPrinter()` in `apps/web/src/hooks/use-electron-printer.ts`
|
||||
|
||||
---
|
||||
|
||||
### Auto-Updater Subsystem
|
||||
|
||||
| Channel | Direction | Pattern | Payload | Access Control |
|
||||
| ----------------------- | --------------- | ------------------- | -------------------------------------------------------------- | ---------------------------------- |
|
||||
| `updater:check` | Renderer → Main | `invoke` / `handle` | Returns update check result | Read-only version query |
|
||||
| `updater:install` | Renderer → Main | `send` / `on` | No payload | Privileged: quits app and installs |
|
||||
| `updater:checking` | Main → Renderer | `send` | No payload | Status notification |
|
||||
| `updater:available` | Main → Renderer | `send` | `UpdateInfo { version, releaseDate, releaseNotes }` | Status notification |
|
||||
| `updater:not-available` | Main → Renderer | `send` | `UpdateInfo` | Status notification |
|
||||
| `updater:progress` | Main → Renderer | `send` | `ProgressInfo { percent, bytesPerSecond, transferred, total }` | Progress telemetry |
|
||||
| `updater:downloaded` | Main → Renderer | `send` | `UpdateInfo` | Status notification |
|
||||
| `updater:error` | Main → Renderer | `send` | Error message string | Error telemetry |
|
||||
|
||||
**Main process handlers:** `setupAutoUpdaterIPC()` + `setupAutoUpdaterEvents()` in `src/main/index.ts`
|
||||
|
||||
**React consumption hook:** `useElectronUpdater()` in `apps/web/src/hooks/use-electron-updater.ts`
|
||||
|
||||
> [!NOTE]
|
||||
> The `updater:install` channel is the **highest-privilege IPC operation** in the system — it terminates the running process and launches a new binary. It should only be triggered by an explicit user action, never automatically.
|
||||
|
||||
---
|
||||
|
||||
## Extending the Bridge: Guided Walkthrough
|
||||
|
||||
**Scenario:** Expose the application version to the React UI.
|
||||
|
||||
### 1. Main Process — Register Handler
|
||||
|
||||
```typescript
|
||||
// In app.whenReady() callback, src/main/index.ts
|
||||
ipcMain.handle('app:get-version', () => {
|
||||
return app.getVersion();
|
||||
});
|
||||
```
|
||||
|
||||
### 2. Preload Gateway — Expose Method
|
||||
|
||||
```typescript
|
||||
// Add to the electronAPI object, src/preload/index.ts
|
||||
const electronAPI = {
|
||||
// ... existing methods ...
|
||||
getAppVersion: (): Promise<string> => {
|
||||
return ipcRenderer.invoke('app:get-version');
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### 3. TypeScript Interface — Declare Type
|
||||
|
||||
```typescript
|
||||
// Add to ElectronAPI interface, apps/web/src/types/electron.d.ts
|
||||
interface ElectronAPI {
|
||||
// ... existing methods ...
|
||||
getAppVersion: () => Promise<string>;
|
||||
}
|
||||
```
|
||||
|
||||
### 4. React — Consume
|
||||
|
||||
```tsx
|
||||
function VersionBadge() {
|
||||
const [version, setVersion] = useState('');
|
||||
|
||||
useEffect(() => {
|
||||
if (window.electronAPI) {
|
||||
window.electronAPI.getAppVersion().then(setVersion);
|
||||
}
|
||||
}, []);
|
||||
|
||||
if (!version) return null;
|
||||
return <span className="version-badge">v{version}</span>;
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Update This Manifest
|
||||
|
||||
After implementing a new channel, **add it to the Verified Channel Manifest** in this document. Undocumented channels are unauthorized channels.
|
||||
|
||||
---
|
||||
|
||||
## Critical Audit Checklist: Anti-Patterns
|
||||
|
||||
The following patterns constitute **critical security violations**. Each one expands the attack surface from "browser-level sandboxed web content" to "unrestricted OS-level code execution." Their presence in production code warrants **immediate incident response**.
|
||||
|
||||
---
|
||||
|
||||
### ❌ Exposing raw `ipcRenderer`
|
||||
|
||||
```typescript
|
||||
// VIOLATION: Catastrophic Failure — Total Attack Surface Expansion
|
||||
contextBridge.exposeInMainWorld('ipc', ipcRenderer);
|
||||
```
|
||||
|
||||
**Threat:** The renderer gains **unrestricted IPC access** — it can invoke any channel, including channels that were never intended to be callable from the renderer. A single XSS vulnerability escalates to arbitrary native code execution.
|
||||
|
||||
**Classification:** **Total System Compromise**
|
||||
|
||||
---
|
||||
|
||||
### ❌ Exposing `require` or Node.js APIs
|
||||
|
||||
```typescript
|
||||
// VIOLATION: Unauthenticated Code Execution
|
||||
contextBridge.exposeInMainWorld('require', require);
|
||||
```
|
||||
|
||||
**Threat:** The renderer can `require('child_process').exec('rm -rf /')`. A single XSS vulnerability in _any_ dependency — including transitive ones — escalates to **full filesystem access, credential theft, reverse shells, and data exfiltration**.
|
||||
|
||||
**Classification:** **Total System Compromise**
|
||||
|
||||
---
|
||||
|
||||
### ❌ Enabling `nodeIntegration`
|
||||
|
||||
```typescript
|
||||
// VIOLATION: Catastrophic Failure — Complete Boundary Collapse
|
||||
new BrowserWindow({
|
||||
webPreferences: { nodeIntegration: true, contextIsolation: false },
|
||||
});
|
||||
```
|
||||
|
||||
**Threat:** Every `<script>` tag in the renderer — including XSS payloads, compromised npm packages, and injected analytics scripts — gains full Node.js capabilities. The isolation boundary **ceases to exist**.
|
||||
|
||||
**Classification:** **Total System Compromise**
|
||||
|
||||
---
|
||||
|
||||
### ❌ Passing unsanitized IPC data to shell commands
|
||||
|
||||
```typescript
|
||||
// VIOLATION: Command Injection — Unauthenticated Code Execution
|
||||
ipcMain.handle('run-cmd', (_event, cmd: string) => {
|
||||
exec(cmd); // The renderer controls the command string
|
||||
});
|
||||
```
|
||||
|
||||
**Threat:** The renderer can execute **arbitrary system commands** with the privileges of the Electron main process (typically the current user). This is the most direct path from XSS to OS-level compromise.
|
||||
|
||||
**Classification:** **Unauthenticated Code Execution**
|
||||
|
||||
---
|
||||
|
||||
### ❌ Registering overly broad IPC channels
|
||||
|
||||
```typescript
|
||||
// VIOLATION: Attack Surface Expansion — Unrestricted File Read
|
||||
ipcMain.handle('file:read', (_event, path: string) => {
|
||||
return readFileSync(path, 'utf-8'); // No validation
|
||||
});
|
||||
```
|
||||
|
||||
**Threat:** The renderer can read **any file** on the filesystem — SSH keys, environment files, database credentials, browser cookies. Input validation is not optional.
|
||||
|
||||
**Classification:** **Sensitive Data Exfiltration**
|
||||
|
||||
---
|
||||
|
||||
## The Gold Standard for Native Integration
|
||||
|
||||
The following patterns represent the **mandatory standard** for all IPC implementations. Adherence is non-negotiable.
|
||||
|
||||
### ✅ Validate and constrain all IPC arguments
|
||||
|
||||
```typescript
|
||||
// GOLD STANDARD: Input validation, path confinement, scope restriction
|
||||
ipcMain.handle('file:read', async (_event, filename: string) => {
|
||||
// Reject path separators — confine to a single directory
|
||||
if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
|
||||
throw new Error('Invalid filename');
|
||||
}
|
||||
|
||||
// Resolve within a controlled directory only
|
||||
const safePath = join(app.getPath('userData'), 'data', filename);
|
||||
|
||||
// Verify the resolved path stays within bounds
|
||||
if (!safePath.startsWith(join(app.getPath('userData'), 'data'))) {
|
||||
throw new Error('Path traversal detected');
|
||||
}
|
||||
|
||||
return readFileSync(safePath, 'utf-8');
|
||||
});
|
||||
```
|
||||
|
||||
**Principle:** Never trust data originating from the renderer. Validate types, constrain scope, and verify resolved paths.
|
||||
|
||||
---
|
||||
|
||||
### ✅ Return unsubscribe functions — Memory Leak Mitigation
|
||||
|
||||
```typescript
|
||||
// GOLD STANDARD: The createEventSubscription helper ensures automatic cleanup
|
||||
function createEventSubscription<T>(channel: string) {
|
||||
return (callback: (data: T) => void): (() => void) => {
|
||||
const handler = (_event: Electron.IpcRendererEvent, data: T) => callback(data);
|
||||
ipcRenderer.on(channel, handler);
|
||||
|
||||
// Return an unsubscribe function — critical for React lifecycle
|
||||
return () => {
|
||||
ipcRenderer.removeListener(channel, handler);
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**In React's `useEffect`:**
|
||||
|
||||
```tsx
|
||||
useEffect(() => {
|
||||
if (!window.electronAPI) return;
|
||||
|
||||
// Subscribe — handler is registered in the Preload's IPC layer
|
||||
const unsub = window.electronAPI.onSomeEvent((data) => {
|
||||
setState(data);
|
||||
});
|
||||
|
||||
// Cleanup on unmount — prevents listener accumulation
|
||||
return () => unsub();
|
||||
}, []);
|
||||
```
|
||||
|
||||
**Principle:** Without the unsubscribe pattern, every component mount adds a **new IPC listener** that persists after unmount. Over time — especially with React's StrictMode double-mounting in development — this causes **memory leaks**, **duplicate event handling**, and **performance degradation**. The `createEventSubscription` helper enforces automatic, deterministic cleanup tied to React's component lifecycle.
|
||||
|
||||
---
|
||||
|
||||
### ✅ Gate all Electron calls behind runtime detection
|
||||
|
||||
```typescript
|
||||
// GOLD STANDARD: Environment-safe consumption
|
||||
function useElectronFeature() {
|
||||
const isElectron = typeof window !== 'undefined' && !!window.electronAPI;
|
||||
|
||||
const doSomething = useCallback(() => {
|
||||
if (!window.electronAPI) return; // No-op in browser
|
||||
window.electronAPI.someMethod();
|
||||
}, []);
|
||||
|
||||
return { isElectron, doSomething };
|
||||
}
|
||||
```
|
||||
|
||||
**Principle:** The React app must run identically in both Electron and standard browser environments. All `window.electronAPI` access must be gated behind a runtime check. Never assume the IPC bridge exists.
|
||||
@@ -0,0 +1,186 @@
|
||||
# Desktop
|
||||
|
||||
The native gateway for our monorepo applications.
|
||||
|
||||
> This package serves as a secure, high-performance Electron wrapper that transforms our web-based assets into first-class desktop experiences. Built on top of **electron-vite** for near-instant development cycles and **electron-builder** for seamless cross-platform distribution.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# From the monorepo root
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Development (starts both the web dev server and Electron)
|
||||
pnpm dev:desktop
|
||||
|
||||
# Build for production
|
||||
pnpm build:desktop
|
||||
|
||||
# Package for distribution
|
||||
pnpm package:desktop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
| Environment | Operational Logic |
|
||||
|---|---|
|
||||
| **Development** | Bridges the Electron shell with the Vite Dev Server, enabling Hot Module Replacement (HMR) and real-time UI synchronization at `http://localhost:5173`. |
|
||||
| **Production** | Orchestrates a Secure Custom Protocol (`app://`) to serve optimized static assets, ensuring seamless SPA client-side routing via an intelligent `index.html` fallback mechanism. |
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
apps/desktop/
|
||||
├── docs/ # Architecture & Operations Documentation
|
||||
│ ├── CONFIGURATION.md # Target app switching, routing fallback procedures
|
||||
│ ├── AUTO_UPDATER.md # Release lifecycle, CI/CD, code signing
|
||||
│ └── IPC_ARCHITECTURE.md # Security model, extensibility patterns
|
||||
├── scripts/
|
||||
│ └── copy-web-dist.ts # Prebuild bridge: syncs web build → web-dist/
|
||||
├── src/
|
||||
│ ├── main/
|
||||
│ │ └── index.ts # Main process: protocol, CORS, IPC, updater
|
||||
│ ├── preload/
|
||||
│ │ └── index.ts # Secure contextBridge API surface
|
||||
│ └── renderer/
|
||||
│ └── index.html # Renderer shell
|
||||
├── .env # Runtime configuration
|
||||
├── electron-builder.yml # Packaging & auto-update provider config
|
||||
├── electron-vite.config.ts # Three-target build config (main, preload, renderer)
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── tsconfig.main.json
|
||||
├── tsconfig.preload.json
|
||||
└── tsconfig.renderer.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scripts
|
||||
|
||||
### Development & Build
|
||||
|
||||
| Script | Description |
|
||||
|---|---|
|
||||
| `pnpm dev` | Launch the electron-vite development server with live reload |
|
||||
| `pnpm build` | Compile main, preload, and renderer TypeScript modules → `out/` |
|
||||
| `pnpm prebuild` | Synchronize the target web app's build output via `scripts/copy-web-dist.ts` — copies `apps/<DESKTOP_TARGET_APP>/dist/` → `web-dist/`. Invoked automatically before `pnpm build`. |
|
||||
| `pnpm preview` | Preview the compiled Electron app locally without generating a distributable |
|
||||
|
||||
### 🚀 Packaging & Distribution
|
||||
|
||||
To generate a production-ready installer, execute from **within `apps/desktop/`** or use the root-level `pnpm package:*` commands, which orchestrate the full pipeline automatically:
|
||||
|
||||
| Command | Platform | Output Artifact |
|
||||
|---|---|---|
|
||||
| `pnpm package` | 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` |
|
||||
|
||||
All artifacts are emitted to the `release/` directory.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Deterministic Build Pipeline**: All `package:*` commands strictly enforce a deterministic build pipeline: compiling web assets via Turborepo, synchronizing the output via the `prebuild` bridge (`node --import tsx scripts/copy-web-dist.ts`), and finally generating the native binary through `electron-builder`.
|
||||
>
|
||||
> **Running locally within `apps/desktop/`**: These scripts assume the web app has already been compiled. Either run `pnpm build --filter=web` beforehand, or use the root-level `pnpm package:*` commands which handle the complete orchestration.
|
||||
|
||||
> [!WARNING]
|
||||
> **macOS Code Signing**: Distributable macOS builds with Auto-Update capability **require** an Apple Developer Certificate. Provide the following environment variables:
|
||||
> ```bash
|
||||
> CSC_LINK=<base64-encoded .p12 certificate>
|
||||
> CSC_KEY_PASSWORD=<certificate password>
|
||||
> APPLE_ID=<your apple id>
|
||||
> APPLE_APP_SPECIFIC_PASSWORD=<app-specific password>
|
||||
> APPLE_TEAM_ID=<team id>
|
||||
> ```
|
||||
> Without valid code signing, macOS Gatekeeper will quarantine the application and `electron-updater` will reject update payloads. See [AUTO_UPDATER.md](./AUTO_UPDATER.md) for the complete requirements.
|
||||
|
||||
> [!NOTE]
|
||||
> **Cross-Compilation Advisory**: It is strongly recommended to build for each platform on its native OS. Cross-compilation (e.g., producing `.dmg` on Linux) may fail due to platform-specific toolchain dependencies. For CI, leverage a matrix strategy:
|
||||
> ```yaml
|
||||
> strategy:
|
||||
> matrix:
|
||||
> os: [macos-latest, windows-latest, ubuntu-latest]
|
||||
> runs-on: ${{ matrix.os }}
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
The target web application is configured via `.env`:
|
||||
|
||||
```env
|
||||
DESKTOP_TARGET_APP=web
|
||||
DESKTOP_DEV_SERVER_URL=http://localhost:5173
|
||||
```
|
||||
|
||||
See [CONFIGURATION.md](./CONFIGURATION.md) for comprehensive guidance on target app switching, protocol internals, and the HashRouter fallback procedure.
|
||||
|
||||
---
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
### 🌐 Custom `app://` Protocol
|
||||
|
||||
Provides a secure file-serving layer with built-in **Path Traversal Protection** and automated **CSP Header Injection**. All requests to unknown paths are intelligently rerouted to `index.html`, enabling React Router to resolve routes client-side without blank screens or 404 errors.
|
||||
|
||||
### 🖨️ Hardware Bridge
|
||||
|
||||
Enables granular control over system peripherals — such as printers — through an asynchronous IPC communication layer. The React app can enumerate connected printers and dispatch print jobs via `window.electronAPI.getPrinters()` and `window.electronAPI.print()`, all without exposing native APIs to the renderer.
|
||||
|
||||
### 🔄 Auto-Update Engine
|
||||
|
||||
A fully managed update lifecycle powered by `electron-updater`. Background download progress is forwarded in real-time to the React UI via IPC event subscriptions, enabling rich notification experiences. See [AUTO_UPDATER.md](./AUTO_UPDATER.md).
|
||||
|
||||
### 🛡️ CORS Bypass Proxy
|
||||
|
||||
A transparent proxy mechanism that handles cross-origin requests by sanitizing non-standard `app://` and `file://` Origin headers on outgoing requests and injecting permissive CORS response headers on incoming responses — allowing seamless integration with cloud APIs without server-side configuration changes.
|
||||
|
||||
### 🔒 Single Instance Lock & Data Integrity
|
||||
|
||||
The application enforces a **single running instance** via `app.requestSingleInstanceLock()`. If a user attempts to launch a second instance, the duplicate process is terminated immediately and the existing window is restored and focused. This mechanism serves two critical purposes:
|
||||
|
||||
- **Data Integrity**: Prevents race conditions and write conflicts in local databases (IndexedDB/PouchDB) that could arise from concurrent access by multiple Electron processes.
|
||||
- **Resource Efficiency**: Avoids duplicate memory allocation, IPC handler registration, and protocol handler conflicts.
|
||||
|
||||
---
|
||||
|
||||
## Hardened Security Perimeter
|
||||
|
||||
The Desktop Wrapper enforces a **hardened security perimeter**, strictly isolating the Node.js Main Process from the Renderer Context. Our architecture is built upon the principle of **Least Privilege**, ensuring that the web application only interacts with system hardware through a verified, secure IPC bridge.
|
||||
|
||||
| Setting | Value | Purpose |
|
||||
|---|---|---|
|
||||
| `contextIsolation` | `true` | Preload executes in a hermetically sealed JavaScript context |
|
||||
| `nodeIntegration` | `false` | Zero Node.js API surface exposed to the renderer |
|
||||
| `sandbox` | `true` | Chromium OS-level sandbox enforced |
|
||||
| `webSecurity` | `true` | Same-origin policy strictly upheld |
|
||||
|
||||
**Defense-in-depth protections in `src/main/index.ts`**:
|
||||
|
||||
- **Path Traversal Guard** — The `app://` protocol handler validates all resolved file paths remain within the `web-dist/` boundary using `normalize()` + `startsWith()`. Traversal attempts like `app://-/../../etc/passwd` are met with `403 Forbidden`.
|
||||
- **CSP Header Injection** — Content-Security-Policy headers are injected as HTTP response headers on every HTML response served by the custom protocol — not via a `<meta>` tag — ensuring they cannot be stripped or bypassed by injected scripts.
|
||||
- **Origin Sanitization** — `session.defaultSession.webRequest` intercepts all outgoing requests, stripping `app://` / `file://` Origin headers to prevent backend CORS rejections.
|
||||
- **Navigation Guard** — The `will-navigate` event intercepts and blocks all navigation attempts to URLs outside the `app://` protocol and the authorized dev server origin.
|
||||
|
||||
See [IPC_ARCHITECTURE.md](./IPC_ARCHITECTURE.md) for the full security model, the Three-Step Bridge pattern, and guidance on safely extending the app with new native features.
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
| Document | Scope |
|
||||
|---|---|
|
||||
| [CONFIGURATION.md](./CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback procedure |
|
||||
| [AUTO_UPDATER.md](./AUTO_UPDATER.md) | Release lifecycle, CI/CD variables, provider switching, code signing |
|
||||
| [IPC_ARCHITECTURE.md](./IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, existing IPC channels, extensibility guide |
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
layout: home
|
||||
hero:
|
||||
name: "Frontend Monorepo Template Docs"
|
||||
text: "Centralized Documentation Engine"
|
||||
tagline: "Enterprise-ready Web & Desktop architecture documentation."
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Get Started
|
||||
link: /packages/core-api/
|
||||
- theme: alt
|
||||
text: UI Components
|
||||
link: /packages/ui/
|
||||
features:
|
||||
- title: Centralized Source of Truth
|
||||
details: All documentation for apps and packages is unified here.
|
||||
- title: Markdown Powered
|
||||
details: Simple to maintain and read.
|
||||
- title: Built with VitePress
|
||||
details: Fast, responsive, and reliable documentation engine.
|
||||
---
|
||||
@@ -0,0 +1,95 @@
|
||||
# Monorepo Architecture Overview
|
||||
|
||||
## 📂 Repository Structure
|
||||
|
||||
The monorepo is organized into **Apps** (deployable applications) and **Packages** (shared libraries).
|
||||
|
||||
```text
|
||||
.
|
||||
├── apps/
|
||||
│ ├── web/ # Main React Application (Vite + TypeScript)
|
||||
│ ├── landing/ # Public Promotional SPA (Vite + TypeScript)
|
||||
│ ├── desktop/ # Electron Desktop Wrapper (electron-vite)
|
||||
│ └── docs-dev/ # Component Documentation & Playground (VitePress)
|
||||
│
|
||||
├── packages/
|
||||
│ ├── core-api/ # Shared HTTP Client, Observability & Data Services Engine
|
||||
│ ├── core-storage/ # Enterprise Storage Engine (IndexedDB/localStorage + Encryption)
|
||||
│ ├── core-i18n/ # Enterprise Internationalization Architecture
|
||||
│ ├── ui/ # Shared UI Component Library
|
||||
│ ├── utils/ # Shared Utilities (Date, Encryption, Core Logic, etc)
|
||||
│ └── configs/ # Shared Tooling Configurations
|
||||
│ ├── eslint/ # Shared ESLint rules
|
||||
│ └── typescript/ # Shared TypeScript (tsconfig) bases
|
||||
│
|
||||
├── package.json # Root scripts and dependencies
|
||||
├── pnpm-workspace.yaml # pnpm workspace definition
|
||||
└── turbo.json # Turborepo pipeline configuration
|
||||
```
|
||||
|
||||
## 📦 Packages Overview
|
||||
|
||||
### 1. `apps/web`
|
||||
The main consumer-facing application.
|
||||
* Imports business logic from `@repo/utils`
|
||||
* Uses shared UI components from `@repo/ui`
|
||||
|
||||
**Tech Stack**: React, Vite, TypeScript, Tailwind CSS
|
||||
|
||||
### 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
|
||||
|
||||
### 3. `apps/landing`
|
||||
The **public promotional website** — a standalone SPA for the company profile and marketing pages.
|
||||
* Deployed independently to the web (e.g., Vercel) — no interaction with Electron
|
||||
* Consumes shared UI components from `@repo/ui` and utilities from `@repo/utils`
|
||||
* Locked to port **3000** (`strictPort: true`) — evacuated from the `517x` range to avoid `electron-vite` port collisions
|
||||
|
||||
### 4. `apps/docs-dev`
|
||||
An isolated environment for developing and documenting UI components.
|
||||
* Ensures components in `@repo/ui` are built and tested independently
|
||||
* Acts as a living design system and playground
|
||||
* Built with **VitePress**
|
||||
|
||||
### 5. `packages/core-api`
|
||||
The **platform-agnostic API engine** for the monorepo. Provides an isolated HTTP client factory, a unified observability pipeline (Grafana Faro + OpenTelemetry), and a generic data services engine.
|
||||
|
||||
### 6. `packages/core-storage`
|
||||
The **Enterprise-grade storage engine** for the monorepo.
|
||||
Provides a unified, Promise-based interface for interacting with browser storage (`localStorage` and `IndexedDB`). Enforces strict type safety, prevents key collisions via a centralized registry, and automatically provides **AES encryption at rest** for sensitive payloads using `@repo/utils`.
|
||||
|
||||
### 7. `packages/core-i18n`
|
||||
The **Enterprise Internationalization Architecture** for the monorepo.
|
||||
Provides a Hybrid Namespace Architecture combining a centralized i18n engine with decentralized, lazy-loaded feature dictionaries. Features strict TypeScript typings (including nested keys), optional backend synchronization with automatic error rollbacks, and a deep-merge mechanism for dynamic tenant-specific vocabulary overrides.
|
||||
|
||||
### 8. `packages/core-events`
|
||||
The **decoupled Nervous System** for the monorepo.
|
||||
Provides a highly performant, strictly typed Event Bus (Pub/Sub) powered by `mitt`. It allows independent modules to communicate seamlessly without tightly coupling their codebases or triggering expensive global React tree re-renders.
|
||||
|
||||
### 9. `packages/utils`
|
||||
Shared business logic and reusable utility modules that can be consumed across multiple applications. Fully tested using Vitest.
|
||||
|
||||
### 10. `packages/ui`
|
||||
Shared UI component library (Buttons, Inputs, Cards, Layouts) with a comprehensive **Form UI Library**.
|
||||
* Ensures consistent design across all applications
|
||||
* Designed to be consumed by both web apps and docs
|
||||
* **Form UI Library**: 22 RHF-connected Mantine form components with Zod validation and i18n error translation, built via a `withRHF()` HOC factory with `useController` micro-subscriptions and `React.memo` optimization for ERP-scale forms
|
||||
|
||||
### 11. `packages/configs`
|
||||
Single source of truth for tooling configuration.
|
||||
* **eslint-config**: Shared ESLint rules
|
||||
* **typescript-config**: Shared `tsconfig.json` base configurations
|
||||
|
||||
## ⚙️ Configuration & Environment
|
||||
|
||||
### Turborepo Caching
|
||||
This repository uses **Turborepo caching** for builds, tests, and other artifacts.
|
||||
To fully clean the workspace (dependencies, build outputs, and Turbo cache):
|
||||
```bash
|
||||
rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist out **/*/out web-dist **/*/web-dist release **/*/release
|
||||
```
|
||||
@@ -0,0 +1,476 @@
|
||||
|
||||
# Enterprise API Engine (`@repo/core-api`)
|
||||
|
||||
The platform-agnostic API engine for the monorepo. Provides an isolated HTTP client factory, a unified observability pipeline (Grafana Faro + OpenTelemetry), and a generic data services engine.
|
||||
|
||||
**This package enforces App Autonomy (IoC).** The core provides the engine and interceptor pipelines, but the consuming applications (`apps/web`, `apps/landing`) inject their own specific configurations, authentication tokens, and error handling behaviors.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef coreEngine fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
|
||||
classDef dataService fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
classDef observability fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
|
||||
classDef errorNode fill:#f43f5e,stroke:#be123c,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Subgraphs ───
|
||||
subgraph Apps ["apps/* (App Autonomy)"]
|
||||
WEB([apps/web])
|
||||
LAND([apps/landing])
|
||||
DESK([apps/desktop])
|
||||
end
|
||||
|
||||
subgraph Core ["@repo/core-api (Engine)"]
|
||||
subgraph HTTP ["http-client"]
|
||||
FACTORY[createHttpClient]
|
||||
end
|
||||
subgraph OBS ["observability"]
|
||||
FARO[faroAdapter]
|
||||
end
|
||||
subgraph DATA ["data-services"]
|
||||
BASE[BaseRemoteDataServices]
|
||||
COMMON[CommonRemoteDataServices]
|
||||
end
|
||||
subgraph ERRORS ["errors"]
|
||||
API_ERR[ApiError]
|
||||
end
|
||||
end
|
||||
|
||||
%% ─── Flow & Relationships ───
|
||||
WEB & LAND & DESK ===>|instantiates| FACTORY
|
||||
WEB & LAND & DESK ===>|extends| COMMON
|
||||
|
||||
COMMON --->|executes via| FACTORY
|
||||
FACTORY -.->|reports via| FARO
|
||||
FACTORY -.->|throws| API_ERR
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class WEB,LAND,DESK appEntity;
|
||||
class FACTORY coreEngine;
|
||||
class BASE,COMMON dataService;
|
||||
class FARO observability;
|
||||
class API_ERR errorNode;
|
||||
|
||||
%% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
|
||||
style Apps fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Core fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
|
||||
|
||||
%% Nested subgraphs also need transparent backgrounds to prevent glaring white boxes in dark mode
|
||||
style HTTP fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
|
||||
style OBS fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
|
||||
style DATA fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
|
||||
style ERRORS fill:transparent,stroke:#cbd5e1,stroke-width:1px,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
### Data Flow Lifecycle
|
||||
|
||||
Every HTTP request flows through this precise interceptor pipeline:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
|
||||
%% ─── Dark-Mode Friendly RGBA Boxes ───
|
||||
box rgba(59,130,246,0.1) App Layer - Consumers
|
||||
participant C as UI Component
|
||||
end
|
||||
|
||||
box rgba(148,163,184,0.1) Core Engine - @repo/core-api
|
||||
participant S as Data Service
|
||||
participant H as HTTP Client
|
||||
participant F as Faro Adapter
|
||||
end
|
||||
|
||||
box rgba(16,185,129,0.1) App Logic - IoC
|
||||
participant A as App Hooks
|
||||
end
|
||||
|
||||
box rgba(245,158,11,0.1) External
|
||||
participant N as Network
|
||||
end
|
||||
|
||||
%% ─── Execution Flow ───
|
||||
C->>S: getMany()
|
||||
S->>H: request()
|
||||
H->>F: onRequestStart() (Log + Span)
|
||||
H->>A: hooks.onRequest() (Inject Token)
|
||||
A->>N: fetch/XHR
|
||||
|
||||
alt Success (2xx)
|
||||
N-->>A: return Response
|
||||
A->>F: onRequestEnd() (Close Span)
|
||||
F->>A: hooks.onResponse()
|
||||
A-->>S: return data
|
||||
else Error (4xx / 5xx)
|
||||
N-->>A: return Rejection
|
||||
A->>F: onRequestError() (Log Error)
|
||||
F->>A: hooks.onResponseError() (Redirect/Refresh)
|
||||
A-->>S: throw ApiError
|
||||
end
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Observability adapter errors are **caught internally** via try-catch in the interceptor chain. An adapter crash will never swallow or replace the original API error — the UI always receives the correct rejection.
|
||||
|
||||
---
|
||||
|
||||
## HTTP Client
|
||||
|
||||
### `createHttpClient(config, hooks?)`
|
||||
|
||||
Creates an **isolated** Axios instance. Each app receives its own interceptor chain — no globals are shared or mutated.
|
||||
|
||||
```typescript
|
||||
import { createHttpClient } from '@repo/core-api/http-client';
|
||||
import { faroAdapter } from '@repo/core-api/observability';
|
||||
|
||||
export const apiClient = createHttpClient(
|
||||
{
|
||||
baseURL: import.meta.env.VITE_API_URL ?? 'http://localhost:8080/api/v1',
|
||||
timeout: 15000,
|
||||
observability: faroAdapter,
|
||||
},
|
||||
{
|
||||
onRequest: async (config) => {
|
||||
const token = localStorage.getItem('access_token');
|
||||
if (token) config.headers.Authorization = `Bearer ${token}`;
|
||||
return config;
|
||||
},
|
||||
onResponseError: async (error) => {
|
||||
if (error.response?.status === 401) {
|
||||
localStorage.removeItem('access_token');
|
||||
window.location.href = '/auth/login';
|
||||
}
|
||||
throw error;
|
||||
},
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
| Property | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `baseURL` | `string` | *required* | Base URL for all requests |
|
||||
| `timeout` | `number` | `15000` | Default request timeout (ms) |
|
||||
| `defaultHeaders` | `Record<string, string>` | `{}` | Headers applied to every request |
|
||||
| `observability` | `IObservabilityAdapter` | `noopAdapter` | Observability adapter (Faro or no-op) |
|
||||
|
||||
### Interceptor Hooks
|
||||
|
||||
| Hook | Signature | Purpose |
|
||||
|---|---|---|
|
||||
| `onRequest` | `(config) => config` | Inject auth tokens, tenant headers |
|
||||
| `onResponse` | `(response) => response` | Transform response shapes |
|
||||
| `onResponseError` | `(error) => never` | App-specific error handling (e.g., 401 redirect) |
|
||||
|
||||
---
|
||||
|
||||
## Observability
|
||||
|
||||
### Strategy: Opt-In Custom Spans + Faro/Loki Baseline
|
||||
|
||||
The observability layer operates in two complementary modes:
|
||||
|
||||
| Mode | Activation | What it does |
|
||||
|---|---|---|
|
||||
| **Baseline** (always on) | Automatic | Pushes structured logs to Faro/Loki on every request with `module.key`, `module.action`, HTTP method, and URL |
|
||||
| **Custom Span** (opt-in) | Via `telemetryContext.customSpanName` | Creates an explicit OTel span with custom tags, visible in Grafana Tempo |
|
||||
|
||||
> [!NOTE]
|
||||
> `trace.getActiveSpan()` returns `undefined` inside Axios interceptors due to browser XHR/Fetch lifecycle race conditions with Faro's `TracingInstrumentation`. The adapter does **not** attempt to enrich auto-instrumented spans. HTTP span capture is handled entirely by `TracingInstrumentation` auto-instrumentation.
|
||||
|
||||
### Initialization
|
||||
|
||||
Call `initTelemetry()` **once** at the top of your app's entry point, before any React code:
|
||||
|
||||
```typescript
|
||||
import { initTelemetry } from '@repo/core-api/observability/setup';
|
||||
|
||||
initTelemetry({
|
||||
appName: 'fe-monorepo-web',
|
||||
appVersion: '1.0.0',
|
||||
telemetryUrl: '[https://telemetry.eigen.co.id/collect](https://telemetry.eigen.co.id/collect)',
|
||||
environment: 'production',
|
||||
// Optional: direct OTLP export to Grafana Tempo
|
||||
otlpTraceUrl: '[https://telemetry.eigen.co.id/v1/traces](https://telemetry.eigen.co.id/v1/traces)',
|
||||
});
|
||||
```
|
||||
|
||||
### `TelemetryConfig`
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `appName` | `string` | ✅ | Application name for Faro + OTel resource attributes |
|
||||
| `appVersion` | `string` | ✅ | SemVer version |
|
||||
| `telemetryUrl` | `string` | ✅ | Grafana Faro collector URL |
|
||||
| `environment` | `string` | ✅ | Deployment environment (`production`, `staging`, `development`) |
|
||||
| `otlpTraceUrl` | `string` | — | Separate OTLP trace endpoint for direct Tempo ingestion |
|
||||
| `propagateTraceHeaderCorsUrls` | `Array<string \| RegExp>` | — | CORS patterns for W3C trace context propagation (default: `[/.*/]`) |
|
||||
|
||||
### Audit Headers
|
||||
|
||||
Every request dispatched through `BaseRemoteDataServices` automatically attaches two business audit headers:
|
||||
|
||||
| Header | Source | Purpose |
|
||||
|---|---|---|
|
||||
| `ex-module-key` | `DataServicesConfig.moduleKey` | Identifies the business module (e.g., `BOOKING`) |
|
||||
| `ex-module-action` | `RequestDescriptor.action` | Identifies the operation (e.g., `READ`, `CREATE`) |
|
||||
|
||||
These headers are extracted by the `faroAdapter` and included in all Faro `pushLog`, `pushError`, and `pushEvent` calls as top-level context — making them directly queryable in **LogQL (Loki)**.
|
||||
|
||||
### Span Safety Guarantees
|
||||
|
||||
| Guarantee | Mechanism |
|
||||
|---|---|
|
||||
| **No span leaks** | `safeEndSpan()` always closes the span and detaches the reference from config |
|
||||
| **No double-close on retry** | Span reference is deleted from config after `span.end()` |
|
||||
| **No error swallowing** | All adapter calls are wrapped in try-catch in `create-http-client.ts` |
|
||||
| **No crash on timeout** | `null`/`undefined` config guards on all `error.config` access |
|
||||
|
||||
---
|
||||
|
||||
## Data Services
|
||||
|
||||
### `CommonRemoteDataServices<E>`
|
||||
|
||||
A concrete, ready-to-use data services class that provides full CRUD and lifecycle operations. Extends `BaseRemoteDataServices<E>`.
|
||||
|
||||
```typescript
|
||||
import { CommonRemoteDataServices } from '@repo/core-api/data-services';
|
||||
import type { BaseEntity } from '@repo/core-api/data-services';
|
||||
import { apiClient } from '@/lib/api-client';
|
||||
|
||||
interface BookingEntity extends BaseEntity {
|
||||
bookingCode: string;
|
||||
customerName: string;
|
||||
status: 'pending' | 'confirmed' | 'cancelled';
|
||||
}
|
||||
|
||||
export const bookingServices = new CommonRemoteDataServices<BookingEntity>(
|
||||
apiClient,
|
||||
{
|
||||
apiUrl: '/bookings',
|
||||
moduleKey: 'BOOKING',
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
### Available Operations
|
||||
|
||||
| Method | HTTP | URL Template | Description |
|
||||
|---|---|---|---|
|
||||
| `getMany(config?)` | GET | `/bookings` | Fetch paginated list |
|
||||
| `getOne(id, config?)` | GET | `/bookings/:id` | Fetch single entity |
|
||||
| `create(data, config?)` | POST | `/bookings` | Create new entity |
|
||||
| `edit(id, data, config?)` | PUT | `/bookings/:id` | Update entity |
|
||||
| `delete(id, config?)` | DELETE | `/bookings/:id` | Delete entity |
|
||||
| `batchDelete(ids, config?)` | DELETE | `/bookings/batch` | Delete multiple |
|
||||
| `activate(id)` | PATCH | `/bookings/:id/activate` | Activate entity |
|
||||
| `deactivate(id)` | PATCH | `/bookings/:id/deactivate` | Deactivate entity |
|
||||
| `confirmProcessData(id)` | PATCH | `/bookings/:id/confirm-process-data` | Confirm data processing |
|
||||
| `confirmProcessTransaction(id)` | PATCH | `/bookings/:id/confirm-process-transaction` | Confirm transaction |
|
||||
| `cancelProcessTransaction(id)` | PATCH | `/bookings/:id/cancel-process-transaction` | Cancel transaction |
|
||||
| `rollbackProcessTransaction(id)` | PATCH | `/bookings/:id/rollback-process-transaction` | Rollback transaction |
|
||||
| `holdProcessTransaction(id)` | PATCH | `/bookings/:id/hold-process-transaction` | Hold transaction |
|
||||
|
||||
All batch variants (`batchActivate`, `batchDeactivate`, etc.) are also available.
|
||||
|
||||
### Escape Hatch: `customRequest<T>(config)`
|
||||
|
||||
For non-standard endpoints that don't fit the CRUD pattern:
|
||||
|
||||
```typescript
|
||||
const taxResult = await bookingServices.customRequest<TaxCalculation>({
|
||||
url: '/bookings/42/calculate-tax',
|
||||
method: 'POST',
|
||||
data: { items: [...] },
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Application Setup Guide
|
||||
|
||||
### 1. Initialize Telemetry (Entry Point)
|
||||
|
||||
```typescript
|
||||
// apps/web/src/main.tsx — MUST be the first import
|
||||
import { initTelemetry } from '@repo/core-api/observability/setup';
|
||||
|
||||
initTelemetry({
|
||||
appName: import.meta.env.VITE_APP_NAME || 'fe-monorepo-web',
|
||||
appVersion: import.meta.env.VITE_APP_VERSION || '0.0.0',
|
||||
telemetryUrl: import.meta.env.VITE_FARO_URL || '[https://telemetry.eigen.co.id/collect](https://telemetry.eigen.co.id/collect)',
|
||||
otlpTraceUrl: import.meta.env.VITE_OTLP_TRACE_URL || '[https://telemetry.eigen.co.id/v1/traces](https://telemetry.eigen.co.id/v1/traces)',
|
||||
environment: import.meta.env.VITE_ENV || 'development',
|
||||
});
|
||||
|
||||
// ... rest of React bootstrap
|
||||
```
|
||||
|
||||
### 2. Create the HTTP Client
|
||||
|
||||
```typescript
|
||||
// apps/web/src/lib/api-client.ts
|
||||
import { createHttpClient } from '@repo/core-api/http-client';
|
||||
import { faroAdapter } from '@repo/core-api/observability';
|
||||
|
||||
export const apiClient = createHttpClient({
|
||||
baseURL: import.meta.env.VITE_API_URL ?? 'http://localhost:8080/api/v1',
|
||||
timeout: 15000,
|
||||
observability: faroAdapter,
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Create a Data Service
|
||||
|
||||
```typescript
|
||||
// features/booking/data/booking.data-services.ts
|
||||
import { CommonRemoteDataServices } from '@repo/core-api/data-services';
|
||||
import type { BaseEntity } from '@repo/core-api/data-services';
|
||||
import { apiClient } from '@/lib/api-client';
|
||||
|
||||
export interface BookingEntity extends BaseEntity {
|
||||
bookingCode: string;
|
||||
customerName: string;
|
||||
status: 'pending' | 'confirmed' | 'cancelled';
|
||||
totalAmount: number;
|
||||
}
|
||||
|
||||
export const bookingServices = new CommonRemoteDataServices<BookingEntity>(
|
||||
apiClient,
|
||||
{ apiUrl: '/bookings', moduleKey: 'BOOKING' },
|
||||
);
|
||||
```
|
||||
|
||||
### 4. Consume in a React Component
|
||||
|
||||
```tsx
|
||||
import { useState } from 'react';
|
||||
import { bookingServices } from '../data/booking.data-services';
|
||||
import type { BookingEntity } from '../data/booking.data-services';
|
||||
import type { ApiResponse } from '@repo/core-api/http-client';
|
||||
import { ApiError } from '@repo/core-api/errors';
|
||||
|
||||
export default function BookingSample() {
|
||||
const [result, setResult] = useState<ApiResponse<BookingEntity[]> | null>(null);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
|
||||
const handleFetch = async () => {
|
||||
try {
|
||||
const response = await bookingServices.getMany<BookingEntity[]>({
|
||||
params: { page: 1, limit: 20 },
|
||||
// Optional: Per-request telemetry escape hatch
|
||||
telemetryContext: {
|
||||
customSpanName: 'booking.list.fetch',
|
||||
tags: { feature: 'booking', page: 1 },
|
||||
pushEventOnSuccess: 'booking_list_loaded',
|
||||
},
|
||||
});
|
||||
setResult(response);
|
||||
} catch (err) {
|
||||
if (err instanceof ApiError) {
|
||||
setError(`[${err.code}] ${err.message} (HTTP ${err.status})`);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
return <button onClick={handleFetch}>Fetch Bookings</button>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Per-Request Telemetry (Escape Hatch)
|
||||
|
||||
### `TelemetryContext`
|
||||
|
||||
Attach to any request via the `telemetryContext` property to push custom spans and business events:
|
||||
|
||||
```typescript
|
||||
interface TelemetryContext {
|
||||
/** Creates a custom OTel span wrapping this request (visible in Grafana Tempo). */
|
||||
customSpanName?: string;
|
||||
/** Custom tags enriching the span and Faro logs (prefixed with `custom.` on spans). */
|
||||
tags?: Record<string, string | number | boolean>;
|
||||
/** Pushes a named Faro event on success (visible in Grafana Faro dashboard). */
|
||||
pushEventOnSuccess?: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Precedence
|
||||
|
||||
`telemetryContext` can be provided at two levels. The top-level `ExecuteOptions.telemetryContext` takes precedence over `config.telemetryContext`:
|
||||
|
||||
```typescript
|
||||
// Top-level (preferred)
|
||||
await bookingServices.getMany({
|
||||
telemetryContext: { customSpanName: 'booking.list.fetch' },
|
||||
});
|
||||
|
||||
// Nested in config (also works)
|
||||
await bookingServices.getMany({
|
||||
params: { page: 1 },
|
||||
telemetryContext: { customSpanName: 'booking.list.fetch' },
|
||||
});
|
||||
```
|
||||
|
||||
### What Happens at Each Stage
|
||||
|
||||
| Stage | Baseline (no telemetryContext) | With `customSpanName` |
|
||||
|---|---|---|
|
||||
| **Request Start** | Faro `pushLog` (DEBUG) with `module.key`, `module.action`, URL | + Creates OTel span with `http.method`, `http.url`, `custom.*` tags |
|
||||
| **Request Success** | — | Closes span (OK). If `pushEventOnSuccess`, pushes Faro event |
|
||||
| **Request Error** | Faro `pushError` + `pushLog` (ERROR) | + Closes span (ERROR), records exception |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### `ApiError`
|
||||
|
||||
All non-2xx responses are normalized into structured `ApiError` instances:
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await bookingServices.getOne('42');
|
||||
} catch (err) {
|
||||
if (err instanceof ApiError) {
|
||||
err.code; // ApiErrorCode.NOT_FOUND
|
||||
err.status; // 404
|
||||
err.message; // "Booking not found"
|
||||
err.data; // Raw server response body
|
||||
err.toJSON(); // Serializable for logging
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Codes
|
||||
|
||||
| Code | HTTP Status | Description |
|
||||
|---|---|---|
|
||||
| `BAD_REQUEST` | 400 | Invalid request parameters |
|
||||
| `UNAUTHORIZED` | 401 | Missing or expired token |
|
||||
| `FORBIDDEN` | 403 | Insufficient permissions |
|
||||
| `NOT_FOUND` | 404 | Resource not found |
|
||||
| `TIMEOUT` | — | Request timed out (`ECONNABORTED`) |
|
||||
| `CANCELLED` | — | Request was cancelled (`ERR_CANCELED`) |
|
||||
| `NETWORK_ERROR` | — | No response received |
|
||||
| `SERVER_ERROR` | 500+ | Internal server error |
|
||||
|
||||
---
|
||||
|
||||
## Package Exports
|
||||
|
||||
| Import Path | Contents |
|
||||
|---|---|
|
||||
| `@repo/core-api/http-client` | `createHttpClient`, `ApiResponse`, `TelemetryContext`, Axios type re-exports |
|
||||
| `@repo/core-api/observability` | `faroAdapter`, `noopObservabilityAdapter`, `IObservabilityAdapter`, `initTelemetry`, `getFaro`, `TelemetryConfig` |
|
||||
| `@repo/core-api/observability/setup` | `initTelemetry`, `getFaro`, `TelemetryConfig` |
|
||||
| `@repo/core-api/data-services` | `BaseRemoteDataServices`, `CommonRemoteDataServices`, types, constants |
|
||||
| `@repo/core-api/errors` | `ApiError`, `ApiErrorCode` |
|
||||
@@ -0,0 +1,365 @@
|
||||
|
||||
# Event Bus (`@repo/core-events`)
|
||||
|
||||
The Global Pub/Sub & Hardware Integration Blueprint.
|
||||
|
||||
> This module provides a strictly-typed, global event bus for the monorepo ecosystem. It decouples cross-component communication and manages real-time hardware signals (such as printers and POS peripherals), ensuring a reactive and memory-safe architecture across all applications.
|
||||
|
||||
---
|
||||
|
||||
## 🧠 System Overview
|
||||
|
||||
`@repo/core-events` is the **decoupled Nervous System** of the ERP. It provides a highly performant, strictly-typed Event Bus powered by `mitt` and custom React hooks.
|
||||
|
||||
**This package is a pure tool.** It ships zero application-specific events. Each consuming app (`apps/web`, `apps/desktop`, etc.) registers its own events autonomously using **TypeScript Declaration Merging** — the exact same Inversion of Control (IoC) pattern utilized by our `@repo/core-api` factory and `@repo/core-storage` engine.
|
||||
|
||||
### Architectural Topology
|
||||
|
||||
### 1. Conceptual Topology: The Pub/Sub Data Flow
|
||||
This diagram illustrates the high-level concept of our decoupled architecture, demonstrating how application-specific types merge into the core bus.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef coreEntity fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#0f172a
|
||||
classDef busEntity fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Nodes ───
|
||||
TYPES[[App-Specific Event Types]]
|
||||
PUB([Publisher Component])
|
||||
BUS{Global Event Bus 'mitt'}
|
||||
SUB([Subscriber Component])
|
||||
|
||||
%% ─── Flow ───
|
||||
TYPES -.->|Declaration Merging| BUS
|
||||
PUB ===>|emit 'event', payload| BUS
|
||||
BUS ===>|useAppEvent 'event'| SUB
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class TYPES,PUB,SUB appEntity;
|
||||
class BUS busEntity;
|
||||
```
|
||||
|
||||
### 2. System Architecture: Core Engine vs. App Autonomy
|
||||
This detailed diagram shows the exact boundaries between the @repo/core-events engine and the consuming application, highlighting real-world publishers (e.g., Cashier UI) and subscribers.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef appComponent fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef injection fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
|
||||
classDef registry fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
classDef coreBus fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Subgraphs ───
|
||||
subgraph Core ["@repo/core-events (Pure Tool)"]
|
||||
R[AppEventRegistry Empty Interface]
|
||||
T[AppEvents Mapped Type]
|
||||
E((Global Event Bus mitt))
|
||||
H[Hooks: useAppEvent / usePublishEvent]
|
||||
end
|
||||
|
||||
subgraph Apps ["apps/web (App Autonomy)"]
|
||||
D[[events.d.ts Declaration Merging]]
|
||||
|
||||
%% Publishers
|
||||
A([Cashier UI])
|
||||
B([Profile Settings])
|
||||
C([WebSocket Client])
|
||||
|
||||
%% Subscribers
|
||||
X([Electron IPC Bridge])
|
||||
Y([IndexedDB Sync])
|
||||
Z([Stock Grid Row])
|
||||
end
|
||||
|
||||
%% ─── Flow & Relationships ───
|
||||
D -.->|Augments| R
|
||||
R ---> T ---> E
|
||||
E ---> H
|
||||
|
||||
%% Emitting Events
|
||||
A ===>|DEVICE:PRINT_RECEIPT| E
|
||||
B ===>|AUTH:PROFILE_UPDATED| E
|
||||
C ===>|WS:STOCK_UPDATE| E
|
||||
|
||||
%% Subscribing to Events
|
||||
E -.->|Triggers| X
|
||||
E -.->|Triggers| Y
|
||||
E -.->|Triggers| Z
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class A,B,C,X,Y,Z appComponent;
|
||||
class D injection;
|
||||
class R,T registry;
|
||||
class E,H coreBus;
|
||||
|
||||
%% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
|
||||
style Core fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Apps fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
### Core Value Proposition
|
||||
|
||||
By routing communication through this centralized event bus, we achieve:
|
||||
|
||||
* **App Autonomy**: The core defines the engine. The app defines the contract. There is zero circular dependency.
|
||||
* **Zero Coupling**: Publishers and subscribers do not need to import, reference, or know about each other's existence.
|
||||
* **Extreme Performance**: Components can subscribe to high-frequency data streams (like WebSockets or hardware signals) and update their own local state *without* triggering massive React tree re-renders.
|
||||
* **Memory Safety**: The provided `useAppEvent` hook automatically handles subscription cleanup on component unmount, proactively preventing the most common source of memory leaks in Single Page Architectures (SPAs).
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Defining Events (Module Augmentation)
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Do NOT add application events to `packages/core-events/src/events.registry.ts`.**
|
||||
> The core registry is intentionally empty. Each app owns its own event contract.
|
||||
|
||||
The core exports an open `AppEventRegistry` interface. Apps extend it using TypeScript's `declare module` syntax — the same pattern used for `@types/*` across the JS ecosystem.
|
||||
|
||||
### Step 1: Create an augmentation file in your app
|
||||
|
||||
> [!WARNING]
|
||||
> The `import type {}` line is **mandatory**. Without it, TypeScript treats `declare module` as an ambient module declaration that **replaces** the module's types instead of merging into them. All actual exports (`useAppEvent`, `publish`, etc.) would become invisible.
|
||||
|
||||
```typescript
|
||||
// apps/web/src/types/events.d.ts
|
||||
|
||||
// This import makes this file a module augmentation (merge)
|
||||
// instead of an ambient declaration (replace).
|
||||
import type {} from '@repo/core-events';
|
||||
|
||||
declare module '@repo/core-events' {
|
||||
// Define your payload shapes
|
||||
interface OrderPayload {
|
||||
orderId: string;
|
||||
total: number;
|
||||
items: Array<{ sku: string; qty: number }>;
|
||||
}
|
||||
|
||||
// Extend the registry
|
||||
interface AppEventRegistry {
|
||||
'STORE:ORDER_PLACED': OrderPayload;
|
||||
'STORE:ORDER_CANCELLED': { orderId: string; reason: string };
|
||||
'UI:SIDEBAR_TOGGLED': { collapsed: boolean };
|
||||
|
||||
// Explicit payloads for the examples below:
|
||||
'DEVICE:PRINT_RECEIPT': { receiptId: string; items: any[]; total: number; cashierName: string; timestamp: number };
|
||||
'WS:STOCK_UPDATE': { id: string; price: number };
|
||||
'AUTH:PROFILE_UPDATED': { id: string; name: string; email: string; avatar: string; updatedAt: number };
|
||||
'SYSTEM:ERROR': { source: string; error: Error };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Use it — autocomplete works immediately
|
||||
|
||||
```tsx
|
||||
import { usePublishEvent, useAppEvent } from '@repo/core-events';
|
||||
|
||||
function CheckoutButton() {
|
||||
const publish = usePublishEvent();
|
||||
// ✅ 'STORE:ORDER_PLACED' autocompletes.
|
||||
// ✅ Payload shape is enforced by TypeScript.
|
||||
publish('STORE:ORDER_PLACED', { orderId: '123', total: 99, items: [] });
|
||||
}
|
||||
|
||||
function OrderTracker() {
|
||||
// ✅ payload is fully typed as OrderPayload
|
||||
useAppEvent('STORE:ORDER_PLACED', (payload) => {
|
||||
console.log(payload.orderId); // string
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### Why this pattern?
|
||||
|
||||
| Concern | Old (Hardcoded) | New (Module Augmentation) |
|
||||
|---|---|---|
|
||||
| Core knows about app events? | ❌ Yes — violates IoC | ✅ No — core is a pure tool |
|
||||
| Adding events requires editing core? | ❌ Yes | ✅ No — edit your app's `.d.ts` only |
|
||||
| Multiple apps share the same registry? | ❌ Collision risk | ✅ Each app has its own `.d.ts` |
|
||||
| Type safety / autocomplete | ✅ Works | ✅ Works identically |
|
||||
|
||||
---
|
||||
|
||||
## Usage Outside React (Vanilla TS)
|
||||
|
||||
For utility files, API interceptors, Web Workers, or vanilla functions where React hooks cannot be used, import the raw `eventBus` instance directly.
|
||||
|
||||
```ts
|
||||
import { eventBus } from '@repo/core-events';
|
||||
|
||||
// Publishing
|
||||
eventBus.publish('STORE:ORDER_CANCELLED', { orderId: '123', reason: 'Out of stock' });
|
||||
|
||||
// Subscribing
|
||||
const handler = (payload) => {
|
||||
console.log('Order cancelled:', payload.orderId);
|
||||
};
|
||||
|
||||
eventBus.subscribe('STORE:ORDER_CANCELLED', handler);
|
||||
|
||||
// CRITICAL: Always unsubscribe when done to prevent memory leaks in non-React contexts!
|
||||
eventBus.unsubscribe('STORE:ORDER_CANCELLED', handler);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
Here are three real-world architectural patterns powered by the Event Bus. All event types below are registered in `apps/web/src/types/events.d.ts`, **not** in the core package.
|
||||
|
||||
### Example 1: Hardware Abstraction (Cross-Platform)
|
||||
|
||||
**Problem**: The web app needs to print receipts. If running in a browser, it should use `window.print()`. If running in the Electron wrapper, it must use the secure IPC bridge (`window.electronAPI.print()`). We don't want the UI components cluttered with platform-detection logic.
|
||||
|
||||
**Solution**: The UI publishes a blind event. A headless listener handles the platform routing.
|
||||
|
||||
**Publisher (Cashier UI)**:
|
||||
```tsx
|
||||
import { usePublishEvent } from '@repo/core-events';
|
||||
|
||||
export function CashierUI() {
|
||||
const publish = usePublishEvent();
|
||||
|
||||
const handlePrint = () => {
|
||||
// Fire and forget. Zero knowledge of how printing actually happens.
|
||||
publish('DEVICE:PRINT_RECEIPT', {
|
||||
receiptId: 'RCP-123',
|
||||
items: [],
|
||||
total: 45.00,
|
||||
cashierName: 'Firman',
|
||||
timestamp: Date.now(),
|
||||
});
|
||||
};
|
||||
|
||||
return <Button onClick={handlePrint}>Print Receipt</Button>;
|
||||
}
|
||||
```
|
||||
|
||||
**Subscriber (Headless Listener)**:
|
||||
```tsx
|
||||
import { useAppEvent } from '@repo/core-events';
|
||||
|
||||
export function PrinterListener() {
|
||||
useAppEvent('DEVICE:PRINT_RECEIPT', (payload) => {
|
||||
const isElectron = typeof window !== 'undefined' && !!window.electronAPI;
|
||||
|
||||
if (isElectron) {
|
||||
// Route via secure Electron IPC bridge
|
||||
window.electronAPI.print({ silent: true });
|
||||
} else {
|
||||
// Fallback to standard browser print dialog
|
||||
window.print();
|
||||
}
|
||||
});
|
||||
|
||||
return null; // Renders nothing
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Extreme Performance (High-Frequency Data)
|
||||
|
||||
**Problem**: A massive data grid (1,000+ rows) receives 50 WebSocket updates per second. If the parent grid holds the state and passes it down via props, React will attempt to re-render all 1,000 rows 50 times a second, crushing the browser.
|
||||
|
||||
**Solution**: The parent grid renders empty rows. Each row subscribes to the event bus and filters updates so it only re-renders when its specific data changes.
|
||||
|
||||
**Parent Grid (Never re-renders)**:
|
||||
```tsx
|
||||
export function LiveStockGrid() {
|
||||
// Generates 1000 IDs once. No stock data is stored here!
|
||||
const stockIds = generateStockIds(1000);
|
||||
|
||||
return (
|
||||
<table>
|
||||
<tbody>
|
||||
{stockIds.map((id) => (
|
||||
<StockRow key={id} stockId={id} />
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Child Row (Targeted Updates)**:
|
||||
```tsx
|
||||
import { memo, useState } from 'react';
|
||||
import { useAppEvent } from '@repo/core-events';
|
||||
|
||||
export const StockRow = memo(function StockRow({ stockId }) {
|
||||
const [data, setData] = useState(null);
|
||||
|
||||
useAppEvent('WS:STOCK_UPDATE', (payload) => {
|
||||
// CRITICAL: Filter out events for other rows.
|
||||
// 999 out of 1000 rows will exit here instantly without causing a re-render.
|
||||
if (payload.id !== stockId) return;
|
||||
|
||||
// Only the targeted row updates its local state
|
||||
setData(payload);
|
||||
});
|
||||
|
||||
return (
|
||||
<tr>
|
||||
<td>{stockId}</td>
|
||||
<td>{data?.price}</td>
|
||||
</tr>
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Background Sync (Auth to IndexedDB)
|
||||
|
||||
**Problem**: When a user updates their profile, we need to persist it to the secure local IndexedDB. We don't want to tightly couple our UI forms to the `@repo/core-storage` package.
|
||||
|
||||
**Solution**: The UI form announces the profile update. A dedicated storage listener persists it in the background, properly escalating errors if the storage fails.
|
||||
|
||||
**Publisher (Profile UI)**:
|
||||
```tsx
|
||||
import { usePublishEvent } from '@repo/core-events';
|
||||
|
||||
export function ProfileSettingsUI() {
|
||||
const publish = usePublishEvent();
|
||||
|
||||
const handleSave = () => {
|
||||
publish('AUTH:PROFILE_UPDATED', {
|
||||
id: 'user-1',
|
||||
name: 'Firman',
|
||||
email: 'firman@eigen.co.id',
|
||||
avatar: '[https://example.com/avatar.png](https://example.com/avatar.png)',
|
||||
updatedAt: Date.now(),
|
||||
});
|
||||
};
|
||||
|
||||
return <Button onClick={handleSave}>Save Profile</Button>;
|
||||
}
|
||||
```
|
||||
|
||||
**Subscriber (Storage Sync Listener)**:
|
||||
```tsx
|
||||
import { useAppEvent, usePublishEvent } from '@repo/core-events';
|
||||
import { secureIndexedDB } from '@repo/core-storage';
|
||||
|
||||
export function StorageSyncListener() {
|
||||
const publish = usePublishEvent();
|
||||
|
||||
useAppEvent('AUTH:PROFILE_UPDATED', (payload) => {
|
||||
// Automatically encrypted at rest because 'user_profile'
|
||||
// is defined in ENCRYPTED_KEYS in @repo/core-storage
|
||||
secureIndexedDB.setItem('user_profile', payload).catch((error) => {
|
||||
// Escalate to global error handler instead of swallowing it
|
||||
publish('SYSTEM:ERROR', { source: 'StorageSyncListener', error });
|
||||
});
|
||||
});
|
||||
|
||||
return null;
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,276 @@
|
||||
|
||||
# i18n Architecture (`@repo/core-i18n`)
|
||||
|
||||
A highly decoupled, type-safe internationalization engine for the monorepo.
|
||||
|
||||
It uses a **Hybrid Namespace Strategy**:
|
||||
1. **Centralized Engine**: Setup, local persistence orchestration, and global words (`common`).
|
||||
2. **Decentralized Dictionaries**: Feature-specific translations (`booking`, `billing`) live inside the application modules and are lazy-loaded.
|
||||
|
||||
This architecture strictly adheres to **Inversion of Control (IoC)**. The core engine handles local state and performance, but leaves API, networking, and storage implementation decisions entirely to the consuming applications.
|
||||
|
||||
---
|
||||
|
||||
## Overview Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef coreEngine fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
|
||||
classDef dataStore fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
classDef externalAPI fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Subgraphs ───
|
||||
subgraph Apps ["apps/* (App Autonomy)"]
|
||||
UI([React Components])
|
||||
DICT[[Feature Dictionaries: booking.json]]
|
||||
end
|
||||
|
||||
subgraph Core ["@repo/core-i18n (Engine)"]
|
||||
I18N[i18next Instance]
|
||||
STORE[(core-storage)]
|
||||
COMMON[Common Vocabulary]
|
||||
end
|
||||
|
||||
subgraph Backend ["Backend API (External)"]
|
||||
SYNC([Language Sync Endpoint])
|
||||
TENANT([Tenant Config Endpoint])
|
||||
end
|
||||
|
||||
%% ─── Flow & Relationships ───
|
||||
UI ===>|uses useTranslation| I18N
|
||||
DICT -.->|lazy loads| I18N
|
||||
COMMON --->|preloads| I18N
|
||||
I18N <===>|reads / persists| STORE
|
||||
|
||||
I18N --->|changeLanguage sync| SYNC
|
||||
SYNC -.->|fails? rollback| I18N
|
||||
|
||||
TENANT -.->|applyTenantOverrides| I18N
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class UI,DICT appEntity;
|
||||
class I18N coreEngine;
|
||||
class STORE,COMMON dataStore;
|
||||
class SYNC,TENANT externalAPI;
|
||||
|
||||
%% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
|
||||
style Apps fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Core fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Backend fill:transparent,stroke:#f59e0b,stroke-width:2px,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. App-Level Setup (Bootstrap)
|
||||
|
||||
Initialize the engine *before* your React application mounts to prevent UI flashing. Provide an `I18nStorageAdapter` using Dependency Injection so the core engine can persist the user's language without being tightly coupled to a specific storage implementation.
|
||||
|
||||
```tsx
|
||||
// apps/web/src/main.tsx
|
||||
import { StrictMode } from 'react';
|
||||
import { createRoot } from 'react-dom/client';
|
||||
import { setupI18n } from '@repo/core-i18n';
|
||||
import { secureStorage, AppStorageKey } from './core/storage';
|
||||
import App from './app';
|
||||
|
||||
async function bootstrap() {
|
||||
// Synchronously reads preferred language from injected storage & inits i18next
|
||||
await setupI18n({
|
||||
storageAdapter: {
|
||||
getLanguage: async () => {
|
||||
const stored = await secureStorage.getItem(AppStorageKey.LOCALE);
|
||||
return typeof stored === 'string' ? stored : null;
|
||||
},
|
||||
setLanguage: async (lng: string) => {
|
||||
await secureStorage.setItem(AppStorageKey.LOCALE, lng);
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
createRoot(document.getElementById('app')!).render(
|
||||
<StrictMode><App /></StrictMode>,
|
||||
);
|
||||
}
|
||||
bootstrap();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Module-Level Setup (Decentralized Dictionaries)
|
||||
|
||||
Dictionaries live right next to the UI components that use them.
|
||||
|
||||
### Folder Structure
|
||||
```text
|
||||
apps/web/src/apps/modules/booking/
|
||||
├── presentation/BookingTable.tsx
|
||||
└── locales/
|
||||
├── id/booking.json
|
||||
└── en/booking.json
|
||||
```
|
||||
|
||||
### Lazy Loading & Type Safety
|
||||
Register the namespace when the component mounts. To get native TypeScript autocomplete for nested keys (e.g., `header.title`), augment the global `react-i18next` types.
|
||||
|
||||
**1. Augment Types:**
|
||||
```ts
|
||||
// apps/web/src/types/i18next.d.ts
|
||||
import 'react-i18next';
|
||||
import type { resources as coreResources } from '@repo/core-i18n/src/setup';
|
||||
import bookingEn from '../apps/modules/booking/locales/en/booking.json';
|
||||
|
||||
declare module 'react-i18next' {
|
||||
interface CustomTypeOptions {
|
||||
defaultNS: 'common';
|
||||
resources: typeof coreResources['en'] & { booking: typeof bookingEn };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**2. Use in Component:**
|
||||
```tsx
|
||||
import { useEffect } from 'react';
|
||||
import { i18n, useTranslation } from '@repo/core-i18n';
|
||||
import bookingId from '../locales/id/booking.json';
|
||||
import bookingEn from '../locales/en/booking.json';
|
||||
|
||||
export default function BookingFeature() {
|
||||
const { t } = useTranslation(['common', 'booking']);
|
||||
|
||||
useEffect(() => {
|
||||
i18n.addResourceBundle('id', 'booking', bookingId, true, false);
|
||||
i18n.addResourceBundle('en', 'booking', bookingEn, true, false);
|
||||
}, []);
|
||||
|
||||
return <h1>{t('booking:header.title')}</h1>; // Autocomplete works!
|
||||
}
|
||||
```
|
||||
|
||||
**3. Dynamic Variables (Interpolation):**
|
||||
```json
|
||||
// booking.json
|
||||
{
|
||||
"messages": {
|
||||
"welcome": "Welcome back, {{name}}! You have {{count}} new bookings."
|
||||
}
|
||||
}
|
||||
```
|
||||
```tsx
|
||||
// Inside component
|
||||
<h1>{t('booking:messages.welcome', { name: 'Firman', count: 5 })}</h1>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Usage Outside React Components (Vanilla TS)
|
||||
|
||||
For utility files, API interceptors, or vanilla functions where React hooks cannot be used, import the raw `i18n` instance directly.
|
||||
|
||||
```ts
|
||||
import { i18n } from '@repo/core-i18n';
|
||||
|
||||
// Must specify the namespace explicitly if it's not 'common'
|
||||
export const getErrorMessage = (code: string) => {
|
||||
return i18n.t(`booking:errors.${code}`, { defaultValue: 'Unknown Error' });
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Real-World Implementation Flow
|
||||
|
||||
The engine supports robust flows for authenticated apps, including Tenant Vocabulary Overrides and Backend Synchronization.
|
||||
|
||||
### A. The Tenant Override Flow (After Login)
|
||||
|
||||
If "Company A" calls "Purchasing" -> "Procurement", they shouldn't need a custom build. The backend returns an override config, and the frontend dynamically merges it using `applyTenantOverrides`.
|
||||
|
||||
```tsx
|
||||
// Example inside an AuthProvider or Post-Login useEffect
|
||||
import { useEffect } from 'react';
|
||||
import { applyTenantOverrides } from '@repo/core-i18n';
|
||||
import { api } from '@/api';
|
||||
|
||||
export function AuthProvider({ children }) {
|
||||
useEffect(() => {
|
||||
async function fetchTenantConfig() {
|
||||
try {
|
||||
// 1. Fetch tenant-specific overrides from the API
|
||||
const response = await api.get('/v1/tenant/i18n-config');
|
||||
|
||||
// 2. Inject into the engine.
|
||||
// `deep: true` ensures only provided keys are overridden.
|
||||
applyTenantOverrides(
|
||||
response.data.namespace,
|
||||
response.data.overrides
|
||||
);
|
||||
} catch (err) {
|
||||
console.error("Failed to fetch tenant configuration", err);
|
||||
}
|
||||
}
|
||||
|
||||
fetchTenantConfig();
|
||||
}, []);
|
||||
|
||||
return <>{children}</>;
|
||||
}
|
||||
```
|
||||
|
||||
### B. User Preference Sync (With Rollback)
|
||||
|
||||
When a logged-in user changes their language, we update the UI instantly, save it locally, and sync it to the backend. If the backend fails, the engine automatically rolls back.
|
||||
|
||||
```tsx
|
||||
import { changeLanguage } from '@repo/core-i18n';
|
||||
import { api } from '@/api';
|
||||
|
||||
const handleSwitch = async (newLng: string) => {
|
||||
try {
|
||||
await changeLanguage(newLng, async (lng) => {
|
||||
// The core engine waits for this Promise.
|
||||
// If it throws, the UI reverts to the previous language automatically.
|
||||
await api.patch('/v1/user/profile', { language: lng });
|
||||
});
|
||||
toast.success('Language saved!');
|
||||
} catch (err) {
|
||||
toast.error('Sync failed. Reverted to previous language.');
|
||||
}
|
||||
};
|
||||
```
|
||||
> [!NOTE]
|
||||
> For public pages (like `apps/landing`), simply call `changeLanguage('en')` without the callback function. It will update the UI and local storage instantly without hitting the network.
|
||||
|
||||
---
|
||||
|
||||
## 5. Backend API Contract (For Backend Engineers)
|
||||
|
||||
To support Dynamic Tenant Overrides, the backend must expose an endpoint (e.g., `GET /v1/tenant/i18n-config`).
|
||||
|
||||
### Identification
|
||||
The backend **MUST identify the tenant via the `Authorization` (JWT) header**. The frontend will not send `tenantId` in the query payload to prevent spoofing.
|
||||
|
||||
### Expected JSON Response Format
|
||||
The response must match the structural shape of the frontend dictionary. Because the frontend uses a **Deep Merge** strategy, the backend **only needs to return the specific keys the tenant wishes to override**.
|
||||
|
||||
If the frontend dictionary has `header.title` and `header.subtitle`, and the backend only sends `header.title`, the `subtitle` will safely remain intact.
|
||||
|
||||
**Example Request:**
|
||||
`GET /v1/tenant/i18n-config`
|
||||
*(Authorization: Bearer eyJhbG...)*
|
||||
|
||||
**Expected Response (200 OK):**
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"namespace": "booking",
|
||||
"overrides": {
|
||||
"module_name": "Procurement",
|
||||
"header": {
|
||||
"title": "Procurement List"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,248 @@
|
||||
|
||||
# Storage Engine (`@repo/core-storage`)
|
||||
|
||||
`@repo/core-storage` is the **Enterprise-grade, multi-tool storage engine** for the Eigen Monorepo.
|
||||
|
||||
It provides a unified set of strictly-typed, secure, and fault-tolerant storage mechanisms tailored for React applications. It enforces strict **Inversion of Control (IoC)**—the core engine knows absolutely nothing about your application's business domains; instead, the consuming apps inject their own configurations and types.
|
||||
|
||||
This package provides three primary storage solutions:
|
||||
1. **Secure Local Storage** (Strict Key-Gatekeeping & AES encryption)
|
||||
2. **Secure IndexedDB** (For larger key-value payloads)
|
||||
3. **Offline-First PouchDB** (For document-oriented, bi-directional sync data)
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Secure Key-Value Storage (LocalStorage & IndexedDB)
|
||||
|
||||
Browser storage is notoriously vulnerable to XSS attacks and pollution. The `LocalStorageService` and `IndexedDBService` implement a strict **Gatekeeper** pattern to solve this.
|
||||
|
||||
By forcing developers to register every key explicitly into either `plainTextKeys` or `encryptedKeys`, the engine guarantees:
|
||||
1. No unapproved or rogue keys can ever be written or read (throws a `Security Exception`).
|
||||
2. Highly sensitive tokens (e.g., JWTs) are automatically routed through the `@repo/utils` AES Encryption pipeline before touching the disk.
|
||||
|
||||
### Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef coreEntity fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#0f172a
|
||||
classDef gatekeeper fill:#10b981,stroke:#047857,stroke-width:2px,color:#ffffff
|
||||
classDef encrypt fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
|
||||
classDef error fill:#f43f5e,stroke:#be123c,stroke-width:2px,color:#ffffff
|
||||
classDef database fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Subgraphs ───
|
||||
subgraph Apps ["apps/* (App Autonomy)"]
|
||||
REG[[AppStorageKey Config]]
|
||||
UI([React Components / API])
|
||||
INST{{Storage Instances}}
|
||||
end
|
||||
|
||||
subgraph Core ["@repo/core-storage"]
|
||||
FAC[Factory: createStorage]
|
||||
API[IStorageService API]
|
||||
VAL{Runtime Gatekeeper}
|
||||
ERR>Throws Security Exception]
|
||||
ENC{{AES Encryption Pipeline}}
|
||||
LOCAL[(LocalStorage Adapter)]
|
||||
IDB[(IndexedDB Adapter)]
|
||||
end
|
||||
|
||||
%% ─── Flow & Relationships ───
|
||||
%% 1. Initialization Flow
|
||||
REG -.->|Injects Keys & Config| FAC
|
||||
FAC -.->|Returns| INST
|
||||
|
||||
%% 2. Runtime Execution Flow
|
||||
UI ===>|getItem / setItem| INST
|
||||
INST ---> API
|
||||
API ---> VAL
|
||||
|
||||
%% 3. Gatekeeper Decision Tree
|
||||
VAL -.->|Invalid Key| ERR
|
||||
VAL ===>|Sensitive Key| ENC
|
||||
|
||||
VAL --->|Plain-text Key| LOCAL
|
||||
VAL --->|Plain-text Key| IDB
|
||||
|
||||
%% 4. Post-Encryption Storage
|
||||
ENC ===>|Encrypted Data| LOCAL
|
||||
ENC ===>|Encrypted Data| IDB
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class REG,UI,INST appEntity;
|
||||
class FAC,API coreEntity;
|
||||
class VAL gatekeeper;
|
||||
class ENC encrypt;
|
||||
class ERR error;
|
||||
class LOCAL,IDB database;
|
||||
|
||||
%% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
|
||||
style Apps fill:transparent,stroke:#818cf8,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style Core fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
### Usage & Implementation
|
||||
|
||||
```typescript
|
||||
import { createLocalStorage, createIndexedDB } from '@repo/core-storage';
|
||||
|
||||
// 1. Define allowed keys (Strict Type Safety)
|
||||
export type AppStorageKey = 'THEME' | 'ACCESS_TOKEN' | 'OFFLINE_CACHE';
|
||||
|
||||
// 2. Instantiate Local Storage
|
||||
export const appStorage = createLocalStorage<AppStorageKey>({
|
||||
plainTextKeys: new Set(['THEME']),
|
||||
encryptedKeys: new Set(['ACCESS_TOKEN']), // Auto AES encrypted
|
||||
});
|
||||
|
||||
// 3. Usage
|
||||
await appStorage.setItem('ACCESS_TOKEN', 'ey...'); // Encrypted on disk
|
||||
const theme = await appStorage.getItem('THEME'); // Plaintext on disk
|
||||
```
|
||||
|
||||
### ✅ Do's and ❌ Don'ts
|
||||
|
||||
* **✅ DO use TypeScript Literal Types** for your storage keys (`type Keys = 'A' | 'B'`) to get full IntelliSense.
|
||||
* **✅ DO place Session/Auth tokens** exclusively inside the `encryptedKeys` Set.
|
||||
* **❌ DON'T use native `window.localStorage` directly** anywhere in your React components. It bypasses our encryption and gatekeeper logic.
|
||||
* **❌ DON'T mix domain data.** Keep UI preferences (Theme, Sidebar state) in LocalStorage, and large datasets (Offline Caches) in IndexedDB.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Offline-First Document Storage (PouchDB & CouchDB)
|
||||
|
||||
For complex, document-oriented data that requires fault-tolerance, offline support, and bi-directional cloud synchronization, we use the `PouchDatabaseManager`.
|
||||
|
||||
### Architecture
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
%% ─── Styling Definitions (Dark-Mode Friendly Enterprise Palette) ───
|
||||
classDef appEntity fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
|
||||
classDef coreEntity fill:#e2e8f0,stroke:#64748b,stroke-width:2px,color:#0f172a
|
||||
classDef localDb fill:#6366f1,stroke:#4338ca,stroke-width:2px,color:#ffffff
|
||||
classDef remoteDb fill:#f59e0b,stroke:#b45309,stroke-width:2px,color:#ffffff
|
||||
|
||||
%% ─── Subgraphs ───
|
||||
subgraph UI ["Consuming App (apps/*)"]
|
||||
COMP([React Components / Forms])
|
||||
end
|
||||
|
||||
subgraph CoreStorage ["@repo/core-storage Engine"]
|
||||
MGR[PouchDatabaseManager Factory]
|
||||
L_SALES[(Local PouchDB: Sales)]
|
||||
L_INV[(Local PouchDB: Inventory)]
|
||||
end
|
||||
|
||||
subgraph RemoteServer ["CouchDB Cluster"]
|
||||
R_SALES[(Remote CouchDB: sales_db)]
|
||||
R_INV[(Remote CouchDB: inventory_db)]
|
||||
end
|
||||
|
||||
%% ─── Flow & Relationships ───
|
||||
COMP ===>|Read / Write| L_SALES
|
||||
COMP ===>|Read / Write| L_INV
|
||||
|
||||
MGR -.->|Instantiates Multi-DB| L_SALES
|
||||
MGR -.->|Instantiates Multi-DB| L_INV
|
||||
|
||||
L_SALES <===>|Native Sync Live and Retry| R_SALES
|
||||
L_INV <===>|Native Sync Live and Retry| R_INV
|
||||
|
||||
%% ─── Apply Styles ───
|
||||
class COMP appEntity;
|
||||
class MGR coreEntity;
|
||||
class L_SALES,L_INV localDb;
|
||||
class R_SALES,R_INV remoteDb;
|
||||
|
||||
%% ─── Subgraph Backgrounds (Transparent for Native GitHub Support) ───
|
||||
style UI fill:transparent,stroke:#3b82f6,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style CoreStorage fill:transparent,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 5 5
|
||||
style RemoteServer fill:transparent,stroke:#f59e0b,stroke-width:2px,stroke-dasharray: 5 5
|
||||
```
|
||||
|
||||
### 1. Initialization (IoC Factory)
|
||||
|
||||
The `PouchDatabaseManager` acts as a central singleton. It registers and manages all database instances. If a remote URL is provided, it automatically handles background synchronization.
|
||||
|
||||
```typescript
|
||||
import { PouchDatabaseManager } from '@repo/core-storage';
|
||||
import type { Item } from './types';
|
||||
|
||||
export const dbManager = new PouchDatabaseManager();
|
||||
|
||||
export const itemDB = dbManager.register<Item>({
|
||||
localName: 'items_db',
|
||||
remoteUrl: 'http://admin:password@localhost:5984/items_db'
|
||||
});
|
||||
```
|
||||
|
||||
### 2. CRUD & MongoDB-style Queries
|
||||
|
||||
The registered database returns a `PouchDatabaseWrapper`. This wrapper fully abstracts the raw PouchDB API into clean, Promise-based helpers, auto-handling `_rev` conflicts.
|
||||
|
||||
| Method | Description |
|
||||
|---|---|
|
||||
| `create(data)` | Inserts a new document. Auto-generates `_id` if omitted. |
|
||||
| `update(id, data)` | Auto-fetches the latest `_rev` to merge payloads cleanly. |
|
||||
| `delete(id)` | Auto-fetches the latest `_rev` to safely remove the document. |
|
||||
| `getAll()` | Retrieves all documents (filters out internal `_design/` docs). |
|
||||
| `find(options)` | Queries using MongoDB-style selectors (via `pouchdb-find`). |
|
||||
|
||||
```typescript
|
||||
// Example: Querying data using selectors
|
||||
const expensiveItems = await itemDB.find({
|
||||
selector: { price: { $gt: 100 }, category: 'electronics' }
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Real-Time Reactivity (`onChange` Pub/Sub)
|
||||
|
||||
We implemented a **Publisher-Subscriber (Pub/Sub)** pattern inside the wrapper to handle real-time data changes efficiently. The wrapper maintains a *single* background connection to the changes feed and broadcasts events to all React subscribers.
|
||||
|
||||
```tsx
|
||||
import { useEffect, useCallback, useState } from 'react';
|
||||
import { itemDB } from '../core/db';
|
||||
|
||||
export function InventoryList() {
|
||||
const [items, setItems] = useState([]);
|
||||
|
||||
const loadData = useCallback(async () => {
|
||||
const data = await itemDB.getAll();
|
||||
setItems(data);
|
||||
}, []);
|
||||
|
||||
useEffect(() => {
|
||||
loadData();
|
||||
|
||||
// Subscribe to background sync mutations
|
||||
const unsubscribe = itemDB.onChange(() => {
|
||||
loadData();
|
||||
});
|
||||
|
||||
// CRITICAL: Prevent memory leaks
|
||||
return () => unsubscribe();
|
||||
}, [loadData]);
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ Do's and ❌ Don'ts for PouchDB
|
||||
|
||||
* **✅ DO use `.onChange()`** to make your UI reactive to background cloud syncs.
|
||||
* **✅ DO return the `unsubscribe` function** in your `useEffect` cleanup block to prevent severe memory leaks.
|
||||
* **❌ DON'T use `db.raw.changes()`** inside your React components. It creates zombie WebSocket connections and tightly couples your UI to PouchDB's specific API.
|
||||
* **❌ DON'T pass the `_rev` property** manually when updating or deleting. The wrapper's `update()` and `delete()` methods handle revision fetching automatically.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Troubleshooting
|
||||
|
||||
### CouchDB CORS Infinite Retries
|
||||
By providing a `remoteUrl`, the engine runs bi-directional sync in the background (`live: true, retry: true`). Fault tolerance is guaranteed: if CouchDB crashes, local reads/writes continue uninterrupted.
|
||||
|
||||
However, if your browser blocks CouchDB sync with a **CORS error**, PouchDB will misinterpret this as a network failure and enter an infinite retry loop, flooding your Network tab.
|
||||
|
||||
> **DO NOT try to fix this in the frontend Vite config or proxy!**
|
||||
> This is strictly a CouchDB server policy issue. You must enable CORS directly on the CouchDB cluster (editing its `local.ini` or via its dashboard) to allow `origins`, `credentials`, and `headers`.
|
||||
@@ -0,0 +1,534 @@
|
||||
---
|
||||
outline: [2, 3]
|
||||
---
|
||||
|
||||
# Core App Shell — Layout Engine
|
||||
|
||||
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/components`
|
||||
> **Dependencies**: React 18+, Mantine v8 (`AppShell`), `@mantine/hooks`
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Architecture](#architecture)
|
||||
- [Composition Model](#composition-model)
|
||||
- [File Structure](#file-structure)
|
||||
- [API Reference](#api-reference)
|
||||
- [CoreAppShellConfig](#coreappshellconfig)
|
||||
- [Layout Variants](#layout-variants)
|
||||
- [Features](#features)
|
||||
- [Dimensions](#dimensions)
|
||||
- [Slots](#slots)
|
||||
- [Context API](#context-api)
|
||||
- [Usage Examples](#usage-examples)
|
||||
- [Minimal Setup](#minimal-setup)
|
||||
- [Header-First with Utility Bar](#header-first-with-utility-bar)
|
||||
- [Double Sidebar (Rail + Panel)](#double-sidebar-rail--panel)
|
||||
- [Interactive Config Builder](#interactive-config-builder)
|
||||
- [CorePageContainer](#corepagecontainer)
|
||||
- [Design Decisions & Caveats](#design-decisions--caveats)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The **Core App Shell** is a configuration-driven layout engine that wraps Mantine's `AppShell` component. It provides a single `<CoreAppShell>` component that renders enterprise-grade application frames — complete with headers, sidebars, aside panels, utility bars, and footers — controlled entirely through a declarative `config` object and slot-based content injection.
|
||||
|
||||
Key capabilities:
|
||||
|
||||
- **Three layout variants** — `header-first`, `sidebar-first`, and `top-nav` — covering the most common enterprise SaaS patterns
|
||||
- **Double sidebar** — Google-style rail + contextual panel navigation
|
||||
- **Smart defaults** — Slots auto-detect presence; no explicit feature flags needed for basic layouts
|
||||
- **Responsive out-of-the-box** — Mobile drawer, desktop collapse, and mini-sidebar are all built-in
|
||||
- **State persistence** — Optional `localStorage`-backed sidebar state via `@mantine/hooks`
|
||||
- **Context API** — All layout toggle methods (`toggleMobile`, `toggleDesktop`, `setSidebarVariant`, etc.) are available to any descendant component via `useCoreAppShell()`
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Composition Model
|
||||
|
||||
The layout engine uses a **Provider → Inner** composition pattern:
|
||||
|
||||
```
|
||||
CoreAppShell (Public API)
|
||||
└── CoreAppShellProvider (Context — state management)
|
||||
└── CoreAppShellInner (Layout rendering — consumes context)
|
||||
└── Mantine <AppShell> (CSS Grid engine)
|
||||
├── AppShell.Header ← slots.utilityBar + slots.header
|
||||
├── AppShell.Navbar ← slots.sidebar | slots.sidebarRail + slots.sidebarPanel
|
||||
├── AppShell.Main ← children
|
||||
├── AppShell.Aside ← slots.aside
|
||||
└── AppShell.Footer ← slots.footer
|
||||
```
|
||||
|
||||
The outer `CoreAppShell` is a thin wrapper that instantiates the provider and passes config down. The inner component subscribes to context and derives all layout calculations (navbar width, header height, collapse states) from the live config + user interactions.
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
packages/ui/src/components/core-app-shell/
|
||||
├── types.ts # All TypeScript interfaces and union types
|
||||
├── core-app-shell-context.tsx # Context provider + useCoreAppShell hook
|
||||
├── core-app-shell.tsx # Main component (Public API + Inner renderer)
|
||||
├── core-page-container.tsx # Companion page-level content wrapper
|
||||
└── index.ts # Barrel exports
|
||||
```
|
||||
|
||||
**Source**: `packages/ui/src/components/core-app-shell/`
|
||||
|
||||
---
|
||||
|
||||
## API Reference
|
||||
|
||||
### CoreAppShellConfig
|
||||
|
||||
The top-level configuration object that controls the entire layout:
|
||||
|
||||
```tsx
|
||||
interface CoreAppShellConfig {
|
||||
variant: LayoutVariant;
|
||||
dimensions?: CoreAppShellDimensions;
|
||||
features?: CoreAppShellFeatures;
|
||||
}
|
||||
```
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `variant` | `LayoutVariant` | ✅ | Determines the structural layout mode |
|
||||
| `dimensions` | `CoreAppShellDimensions` | — | Override default pixel dimensions |
|
||||
| `features` | `CoreAppShellFeatures` | — | Toggle optional layout regions and behaviors |
|
||||
|
||||
---
|
||||
|
||||
### Layout Variants
|
||||
|
||||
```tsx
|
||||
type LayoutVariant = 'header-first' | 'sidebar-first' | 'top-nav';
|
||||
```
|
||||
|
||||
| Variant | Mantine `layout` | Visual Description |
|
||||
|---|---|---|
|
||||
| `header-first` | `default` | Header spans the full viewport width. Sidebar and aside sit **below** the header, stretching to the bottom of the screen. Footer is inset between the sidebar and aside. This is the most common enterprise/dashboard pattern (e.g., Azure Portal, Jira). |
|
||||
| `sidebar-first` | `alt` | Sidebar spans the full viewport height. Header sits **to the right** of the sidebar. Produces a "desktop application" feel (e.g., VS Code, Slack). Footer spans full width beneath the sidebar. |
|
||||
| `top-nav` | `default` | Header-only layout with **no visible desktop sidebar**. The sidebar is hidden on desktop but remains accessible as a mobile drawer on small screens. Ideal for documentation sites or marketing pages. |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> When `variant` is set to `top-nav`, the desktop navbar is visually hidden via `collapsed.desktop: true` and width `0`. However, the `<AppShell.Navbar>` DOM element remains mounted with responsive width props so the mobile drawer continues to function. This is an intentional design choice to avoid conditional DOM removal.
|
||||
|
||||
---
|
||||
|
||||
### Features
|
||||
|
||||
```tsx
|
||||
interface CoreAppShellFeatures {
|
||||
desktopCollapseVariant?: DesktopCollapseVariant;
|
||||
withUtilityBar?: boolean;
|
||||
withAside?: boolean;
|
||||
withFooter?: boolean;
|
||||
withDoubleSidebar?: boolean;
|
||||
persistState?: boolean;
|
||||
zIndex?: number;
|
||||
disabled?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
| Property | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `desktopCollapseVariant` | `'hide' \| 'mini'` | `'hide'` | **`hide`**: Sidebar slides out completely (collapsed width = 0). **`mini`**: Sidebar shrinks to `sidebarMiniWidth` showing only icons. |
|
||||
| `withUtilityBar` | `boolean` | Auto-detected | Show the utility bar above the header. If omitted, the bar renders when a `utilityBar` slot is provided. Set explicitly to `false` to suppress. |
|
||||
| `withAside` | `boolean` | Auto-detected | Show the right-hand aside panel. Same auto-detection logic as `withUtilityBar`. |
|
||||
| `withFooter` | `boolean` | Auto-detected | Show the bottom footer. Same auto-detection logic. |
|
||||
| `withDoubleSidebar` | `boolean` | `false` | Enable the **Rail + Panel** double sidebar mode. When `true`, the navbar renders `sidebarRail` and `sidebarPanel` slots instead of the single `sidebar` slot. |
|
||||
| `persistState` | `boolean` | `true` (implied) | Persist sidebar variant (`expanded`/`mini`/`hidden`) to `localStorage` via `useLocalStorage`. Set to `false` for demos or ephemeral layouts. |
|
||||
| `zIndex` | `number` | `200` | Base z-index passed to Mantine's `AppShell`. |
|
||||
| `disabled` | `boolean` | `false` | Disables the AppShell layout entirely (renders children without structural chrome). |
|
||||
|
||||
> [!TIP]
|
||||
> **Smart defaults**: You rarely need to set `withUtilityBar`, `withAside`, or `withFooter` explicitly. The engine auto-detects presence by checking if the corresponding slot is provided and truthy. Only set them to `false` when you want to **suppress** a slot that is being passed.
|
||||
|
||||
---
|
||||
|
||||
### Dimensions
|
||||
|
||||
```tsx
|
||||
interface CoreAppShellDimensions {
|
||||
utilityBarHeight?: number | string;
|
||||
headerHeight?: number | string;
|
||||
sidebarWidth?: number | string;
|
||||
sidebarMiniWidth?: number | string;
|
||||
sidebarRailWidth?: number | string;
|
||||
asideWidth?: number | string;
|
||||
}
|
||||
```
|
||||
|
||||
| Property | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `utilityBarHeight` | `number \| string` | `32` | Height of the utility bar strip above the header |
|
||||
| `headerHeight` | `number \| string` | `60` | Height of the main header |
|
||||
| `sidebarWidth` | `number \| string` | `260` | Width of the expanded sidebar |
|
||||
| `sidebarMiniWidth` | `number \| string` | `80` | Width of the sidebar in `mini` collapse mode |
|
||||
| `sidebarRailWidth` | `number \| string` | `54` | Width of the icon rail in double-sidebar mode |
|
||||
| `asideWidth` | `number \| string` | `260` | Width of the right-hand aside panel |
|
||||
|
||||
> [!NOTE]
|
||||
> All dimension values accept both pixel numbers (e.g., `260`) and CSS strings (e.g., `'20rem'`). When both `headerHeight` and `utilityBarHeight` are numbers, they are summed directly. When either is a string, the engine wraps them in a `calc()` expression automatically.
|
||||
|
||||
---
|
||||
|
||||
### Slots
|
||||
|
||||
Content is injected via the `slots` prop — a flat object of named `ReactNode` values:
|
||||
|
||||
```tsx
|
||||
interface CoreAppShellSlots {
|
||||
utilityBar?: ReactNode;
|
||||
header?: ReactNode;
|
||||
sidebar?: ReactNode;
|
||||
sidebarMobile?: ReactNode;
|
||||
sidebarRail?: ReactNode;
|
||||
sidebarPanel?: ReactNode;
|
||||
aside?: ReactNode;
|
||||
footer?: ReactNode;
|
||||
}
|
||||
```
|
||||
|
||||
| Slot | Location | Notes |
|
||||
|---|---|---|
|
||||
| `utilityBar` | Above the header, hidden on mobile (`display: none` below `sm`) | Typically used for environment banners, announcements, or top-level links. |
|
||||
| `header` | Main application header | Must contain its own `<Burger>` for mobile toggle (use `useCoreAppShell()` context). |
|
||||
| `sidebar` | Desktop navbar body (single-sidebar mode) | Ignored when `withDoubleSidebar` is `true` — use `sidebarRail` + `sidebarPanel` instead. |
|
||||
| `sidebarMobile` | Mobile drawer content | Falls back to `sidebar` if not provided. Use this to render a simplified mobile-specific navigation. |
|
||||
| `sidebarRail` | Narrow icon rail (double-sidebar mode) | Only rendered when `withDoubleSidebar` is `true`. Separated from `sidebarPanel` by a 1px border. |
|
||||
| `sidebarPanel` | Contextual panel beside the rail (double-sidebar mode) | Collapsible via `toggleNavbarPanel()`. Only rendered when `withDoubleSidebar` is `true` and `navbarPanelOpened` is `true`. |
|
||||
| `aside` | Right-hand panel | Collapsible via `toggleAside()`. Only rendered when `withAside` is enabled. |
|
||||
| `footer` | Bottom application footer | In `header-first` mode, the footer is inset between sidebar and aside. In `sidebar-first` mode, it spans the full width. |
|
||||
|
||||
---
|
||||
|
||||
### Context API
|
||||
|
||||
The `useCoreAppShell()` hook provides access to all layout state and toggle methods from any descendant component:
|
||||
|
||||
```tsx
|
||||
import { useCoreAppShell } from '@repo/ui/components';
|
||||
```
|
||||
|
||||
| Property / Method | Type | Description |
|
||||
|---|---|---|
|
||||
| `mobileOpened` | `boolean` | Whether the mobile drawer is currently open |
|
||||
| `desktopOpened` | `boolean` | Whether the desktop sidebar is expanded (only applies when `desktopCollapseVariant` is `'hide'`) |
|
||||
| `sidebarVariant` | `SidebarVariant` | Current sidebar mode: `'expanded'` \| `'mini'` \| `'hidden'` |
|
||||
| `asideOpened` | `boolean` | Whether the aside panel is currently visible |
|
||||
| `navbarPanelOpened` | `boolean` | Whether the secondary panel in double-sidebar mode is expanded |
|
||||
| `config` | `CoreAppShellConfig` | Read-only access to the current layout configuration |
|
||||
| `toggleMobile()` | `() => void` | Toggle the mobile drawer open/closed |
|
||||
| `toggleDesktop()` | `() => void` | Toggle the desktop sidebar open/closed |
|
||||
| `toggleAside()` | `() => void` | Toggle the aside panel visibility |
|
||||
| `toggleNavbarPanel()` | `() => void` | Toggle the double-sidebar panel open/closed |
|
||||
| `setSidebarVariant()` | `(variant: SidebarVariant) => void` | Programmatically set the sidebar to `'expanded'`, `'mini'`, or `'hidden'` |
|
||||
|
||||
> [!WARNING]
|
||||
> `useCoreAppShell()` **must** be called from within a `<CoreAppShell>` subtree. Calling it outside the provider will throw: `"useCoreAppShell must be used within CoreAppShellProvider"`. If you need context access in the header slot, pass a component (not inline JSX) so it mounts inside the provider tree.
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Minimal Setup
|
||||
|
||||
The simplest possible layout — a header and sidebar with all defaults:
|
||||
|
||||
```tsx
|
||||
import { CoreAppShell, CoreAppShellConfig, useCoreAppShell } from '@repo/ui/components';
|
||||
import { Group, Text, Box, Stack, Button, Burger } from '@repo/ui/components';
|
||||
|
||||
function MyHeader() {
|
||||
const { mobileOpened, toggleMobile } = useCoreAppShell();
|
||||
return (
|
||||
<Group h="100%" px="md">
|
||||
<Burger opened={mobileOpened} onClick={toggleMobile} hiddenFrom="sm" size="sm" />
|
||||
<Text fw={700}>My Application</Text>
|
||||
</Group>
|
||||
);
|
||||
}
|
||||
|
||||
const config: CoreAppShellConfig = {
|
||||
variant: 'header-first',
|
||||
};
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<CoreAppShell
|
||||
config={config}
|
||||
slots={{
|
||||
header: <MyHeader />,
|
||||
sidebar: (
|
||||
<Stack p="md" gap="xs">
|
||||
<Button variant="subtle" fullWidth>Dashboard</Button>
|
||||
<Button variant="subtle" fullWidth>Settings</Button>
|
||||
</Stack>
|
||||
),
|
||||
}}
|
||||
>
|
||||
<Text>Main content area</Text>
|
||||
</CoreAppShell>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Header-First with Utility Bar
|
||||
|
||||
A full enterprise layout with utility bar, aside, and footer:
|
||||
|
||||
```tsx
|
||||
import { CoreAppShell, CoreAppShellConfig, useCoreAppShell } from '@repo/ui/components';
|
||||
import { Group, Text, Box, Burger } from '@repo/ui/components';
|
||||
|
||||
function AppHeader() {
|
||||
const { mobileOpened, toggleMobile } = useCoreAppShell();
|
||||
return (
|
||||
<Group h="100%" px="md" justify="space-between">
|
||||
<Group>
|
||||
<Burger opened={mobileOpened} onClick={toggleMobile} hiddenFrom="sm" size="sm" />
|
||||
<Text fw={700} size="lg">Enterprise Dashboard</Text>
|
||||
</Group>
|
||||
</Group>
|
||||
);
|
||||
}
|
||||
|
||||
const config: CoreAppShellConfig = {
|
||||
variant: 'header-first',
|
||||
features: {
|
||||
desktopCollapseVariant: 'hide',
|
||||
persistState: true,
|
||||
},
|
||||
dimensions: {
|
||||
headerHeight: 60,
|
||||
utilityBarHeight: 32,
|
||||
sidebarWidth: 280,
|
||||
asideWidth: 300,
|
||||
},
|
||||
};
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<CoreAppShell
|
||||
config={config}
|
||||
slots={{
|
||||
utilityBar: (
|
||||
<Group h="100%" px="md" justify="flex-end">
|
||||
<Text size="xs">v2.4.1 · Production</Text>
|
||||
</Group>
|
||||
),
|
||||
header: <AppHeader />,
|
||||
sidebar: <MySidebar />,
|
||||
aside: <MyAside />,
|
||||
footer: (
|
||||
<Group h="100%" px="md">
|
||||
<Text size="sm">© 2026 Acme Corp</Text>
|
||||
</Group>
|
||||
),
|
||||
}}
|
||||
>
|
||||
<MyPageContent />
|
||||
</CoreAppShell>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Double Sidebar (Rail + Panel)
|
||||
|
||||
Google-style navigation with an icon rail and a collapsible contextual panel:
|
||||
|
||||
```tsx
|
||||
import { CoreAppShell, CoreAppShellConfig, useCoreAppShell } from '@repo/ui/components';
|
||||
import { Stack, Box, Text, Burger, Group } from '@repo/ui/components';
|
||||
import { Home, Settings, BarChart2 } from 'lucide-react';
|
||||
|
||||
function AppHeader() {
|
||||
const { mobileOpened, toggleMobile } = useCoreAppShell();
|
||||
return (
|
||||
<Group h="100%" px="md">
|
||||
<Burger opened={mobileOpened} onClick={toggleMobile} hiddenFrom="sm" size="sm" />
|
||||
<Text fw={700}>Admin Panel</Text>
|
||||
</Group>
|
||||
);
|
||||
}
|
||||
|
||||
const config: CoreAppShellConfig = {
|
||||
variant: 'sidebar-first',
|
||||
features: {
|
||||
withDoubleSidebar: true,
|
||||
},
|
||||
dimensions: {
|
||||
sidebarRailWidth: 54,
|
||||
sidebarWidth: 260,
|
||||
},
|
||||
};
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<CoreAppShell
|
||||
config={config}
|
||||
slots={{
|
||||
header: <AppHeader />,
|
||||
sidebarRail: (
|
||||
<Stack align="center" gap="lg" pt="md">
|
||||
<Home size={24} />
|
||||
<BarChart2 size={24} />
|
||||
<Settings size={24} />
|
||||
</Stack>
|
||||
),
|
||||
sidebarPanel: (
|
||||
<Box p="md">
|
||||
<Text fw={700} mb="sm">Navigation</Text>
|
||||
{/* Contextual links based on active rail icon */}
|
||||
</Box>
|
||||
),
|
||||
sidebarMobile: (
|
||||
<Box p="md">
|
||||
<Text fw={700}>Mobile Nav</Text>
|
||||
{/* Simplified mobile navigation */}
|
||||
</Box>
|
||||
),
|
||||
}}
|
||||
>
|
||||
<Text>Main content</Text>
|
||||
</CoreAppShell>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> When `withDoubleSidebar` is `true`, the `sidebar` slot is ignored on desktop. The navbar renders `sidebarRail` (fixed-width icon column) and `sidebarPanel` (collapsible contextual panel) side-by-side. On mobile, `sidebarMobile` takes priority, falling back to `sidebar` if not provided.
|
||||
|
||||
---
|
||||
|
||||
### Interactive Config Builder
|
||||
|
||||
The showcase demo at `apps/web/src/apps/showcase/shell-demo/` demonstrates a live, interactive config builder where every feature toggle and variant switch updates the layout in real-time. The key pattern is managing `config` state externally and passing it as a prop:
|
||||
|
||||
```tsx
|
||||
import { useState, useMemo } from 'react';
|
||||
import { CoreAppShell, CoreAppShellConfig, LayoutVariant, DesktopCollapseVariant } from '@repo/ui/components';
|
||||
|
||||
function ShellDemo() {
|
||||
const [layoutVariant, setLayoutVariant] = useState<LayoutVariant>('header-first');
|
||||
const [collapseVariant, setCollapseVariant] = useState<DesktopCollapseVariant>('hide');
|
||||
const [withDoubleSidebar, setWithDoubleSidebar] = useState(false);
|
||||
|
||||
const config: CoreAppShellConfig = useMemo(() => ({
|
||||
variant: layoutVariant,
|
||||
features: {
|
||||
desktopCollapseVariant: collapseVariant,
|
||||
withDoubleSidebar,
|
||||
persistState: false,
|
||||
},
|
||||
}), [layoutVariant, collapseVariant, withDoubleSidebar]);
|
||||
|
||||
return (
|
||||
<CoreAppShell config={config} slots={{ header: <MyHeader />, sidebar: <MySidebar /> }}>
|
||||
{/* Config controls live here — they can use useCoreAppShell() for toggle methods */}
|
||||
</CoreAppShell>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CorePageContainer
|
||||
|
||||
A companion component for structuring page-level content within the `<AppShell.Main>` area. It provides a sticky page header and a contained, padded content region.
|
||||
|
||||
```tsx
|
||||
import { CorePageContainer } from '@repo/ui/components';
|
||||
```
|
||||
|
||||
### Props
|
||||
|
||||
```tsx
|
||||
interface CorePageContainerProps extends ContainerProps {
|
||||
headerSlot?: ReactNode;
|
||||
children: ReactNode;
|
||||
stickyHeader?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
| Prop | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `headerSlot` | `ReactNode` | — | Page-level header content (title, breadcrumbs, action buttons). Rendered above the main content with a bottom border. |
|
||||
| `stickyHeader` | `boolean` | `false` | When `true`, the page header sticks to the top of the scroll area, offset by the AppShell header height via `var(--app-shell-header-offset)`. |
|
||||
| `px` | `MantineSpacing` | `'md'` | Horizontal padding for both the header and content areas |
|
||||
| `py` | `MantineSpacing` | `'md'` | Vertical padding for both the header and content areas |
|
||||
| _...rest_ | `ContainerProps` | — | All other Mantine `Container` props are forwarded to the content region |
|
||||
|
||||
### Usage
|
||||
|
||||
```tsx
|
||||
<CoreAppShell config={config} slots={slots}>
|
||||
<CorePageContainer
|
||||
stickyHeader
|
||||
headerSlot={
|
||||
<Group justify="space-between">
|
||||
<Text component="h1" size="xl" fw={700}>Users</Text>
|
||||
<Button>Add User</Button>
|
||||
</Group>
|
||||
}
|
||||
>
|
||||
<UserTable />
|
||||
</CorePageContainer>
|
||||
</CoreAppShell>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Decisions & Caveats
|
||||
|
||||
### Mobile Navbar Lifecycle
|
||||
|
||||
The `<AppShell.Navbar>` DOM element is **always mounted**, even when the layout variant is `top-nav`. The desktop content is hidden via `visibleFrom="sm"` and mobile content via `hiddenFrom="sm"`. This ensures Mantine's native drawer engine works correctly on mobile without conditional DOM removal breaking the transition animations.
|
||||
|
||||
### Footer Positioning in `header-first` Mode
|
||||
|
||||
In `header-first` mode, the footer is **inset** between the sidebar and aside using CSS custom properties:
|
||||
|
||||
```css
|
||||
left: var(--app-shell-navbar-offset, 0px);
|
||||
right: var(--app-shell-aside-offset, 0px);
|
||||
```
|
||||
|
||||
In `sidebar-first` mode, the footer spans the full viewport width (`left: 0; right: 0`).
|
||||
|
||||
### Z-Index Strategy
|
||||
|
||||
| Element | `header-first` | `sidebar-first` |
|
||||
|---|---|---|
|
||||
| AppShell (base) | `200` (default) | `200` (default) |
|
||||
| Navbar | `105` | `100` |
|
||||
| Aside | `105` | `100` |
|
||||
| Footer | `100` | `100` |
|
||||
|
||||
The elevated `105` z-index for navbar/aside in `header-first` mode ensures they render above the footer, which is positioned at `100`.
|
||||
|
||||
### Sidebar Width Calculation
|
||||
|
||||
The navbar width is dynamically computed based on multiple state variables:
|
||||
|
||||
```
|
||||
navbarWidth.sm =
|
||||
isTopNav → 0
|
||||
isDoubleSidebar + panelOpen → sidebarWidth
|
||||
isDoubleSidebar + panelClosed → sidebarRailWidth
|
||||
sidebarVariant === 'mini' → sidebarMiniWidth
|
||||
default → sidebarWidth
|
||||
```
|
||||
|
||||
On mobile and `xs` breakpoints, the width is always `100%` and `sidebarWidth` respectively, regardless of variant.
|
||||
@@ -0,0 +1,919 @@
|
||||
---
|
||||
outline: [2, 3]
|
||||
---
|
||||
|
||||
# Form UI Library
|
||||
|
||||
> **Package**: `@repo/ui` · **Module Path**: `@repo/ui/form`
|
||||
> **Dependencies**: React Hook Form v7, Zod v3, Mantine v8, `@repo/core-i18n`
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Architecture](#architecture)
|
||||
- [HOC Factory Pattern](#hoc-factory-pattern)
|
||||
- [Naming Conventions](#naming-conventions)
|
||||
- [File Structure](#file-structure)
|
||||
- [Performance & Memoization](#performance--memoization)
|
||||
- [i18n Error Translation](#i18n-error-translation)
|
||||
- [Theme & Style Inheritance](#theme--style-inheritance)
|
||||
- [Validation Layer](#validation-layer)
|
||||
- [Usage Examples](#usage-examples)
|
||||
- [Basic Form](#basic-form)
|
||||
- [With Zod Validation](#with-zod-validation)
|
||||
- [Custom Field Component](#custom-field-component)
|
||||
- [Component Reference](#component-reference)
|
||||
- [Testing](#testing)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Form UI Library provides **22 pre-built form field components** that integrate [Mantine v8](https://mantine.dev/) form components with [React Hook Form (RHF)](https://react-hook-form.com/) and [Zod](https://zod.dev/) validation. Each component is generated via a central `withRHF()` HOC factory, ensuring consistent behavior across:
|
||||
|
||||
- **Value binding** — Two-way data flow between RHF and Mantine
|
||||
- **Error display** — Automatic rendering of validation errors
|
||||
- **i18n translation** — Zod errors can be encoded as JSON payloads for translation
|
||||
- **Performance** — Micro-subscriptions via `useController` + `React.memo`
|
||||
- **Theme compliance** — Zero hardcoded styles; all styling flows from the existing `ThemeProvider`
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### HOC Factory Pattern
|
||||
|
||||
The entire library is built on a single factory function:
|
||||
|
||||
```
|
||||
withRHF<MantineComponentProps>(displayName, MantineComponent, options?)
|
||||
└─► Returns a React.memo'd component that:
|
||||
├── Uses useController() for field-level subscriptions
|
||||
├── Maps field.value/onChange/onBlur to Mantine props
|
||||
├── Intercepts fieldState.error?.message
|
||||
│ ├── Attempts JSON.parse for i18n payloads
|
||||
│ └── Falls back to raw string if not translatable
|
||||
├── Passes error={translated} to Mantine component
|
||||
├── Forwards ref to the underlying DOM element
|
||||
└── Preserves full Mantine TypeScript generics
|
||||
```
|
||||
|
||||
**Source**: `packages/ui/src/components/Form/withRHF.tsx`
|
||||
|
||||
The factory accepts three arguments:
|
||||
|
||||
| Argument | Type | Description |
|
||||
|---|---|---|
|
||||
| `displayName` | `string` | React DevTools name (e.g., `"FieldTextInput"`) |
|
||||
| `MantineComponent` | `ComponentType` | The raw Mantine component |
|
||||
| `options` | `WithRHFOptions` | Optional config for special components |
|
||||
|
||||
#### Options
|
||||
|
||||
| Option | Default | Description |
|
||||
|---|---|---|
|
||||
| `isCheckType` | `false` | Use `checked` instead of `value` (for Checkbox, Switch) |
|
||||
| `requiresWrapper` | `false` | Wrap in `Input.Wrapper` for error display (for ColorPicker, SegmentedControl, Chip.Group) |
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
All wrapped components use the **`Field` prefix** to prevent naming collisions with native Mantine exports:
|
||||
|
||||
```tsx
|
||||
// ✅ Our library — RHF-connected, type-safe
|
||||
import { FieldTextInput } from '@repo/ui/form';
|
||||
|
||||
// ✅ Native Mantine — still accessible via the same package
|
||||
import { TextInput } from '@repo/ui/components';
|
||||
```
|
||||
|
||||
This avoids ambiguity in large codebases where both raw Mantine and form-connected versions might be needed.
|
||||
|
||||
### File Structure
|
||||
|
||||
Each component lives in its own file following the `[kebab-case-name].field.tsx` convention within the `fields/` directory:
|
||||
|
||||
```
|
||||
packages/ui/src/components/Form/
|
||||
├── withRHF.tsx # HOC factory
|
||||
├── types.ts # Shared TypeScript types
|
||||
├── index.ts # Barrel exports
|
||||
├── __tests__/
|
||||
│ ├── withRHF.test.tsx
|
||||
│ ├── text-input.field.test.tsx
|
||||
│ └── checkbox.field.test.tsx
|
||||
└── fields/
|
||||
├── text-input.field.tsx # FieldTextInput
|
||||
├── password-input.field.tsx # FieldPasswordInput
|
||||
├── textarea.field.tsx # FieldTextarea
|
||||
├── number-input.field.tsx # FieldNumberInput
|
||||
├── select.field.tsx # FieldSelect
|
||||
├── multi-select.field.tsx # FieldMultiSelect
|
||||
├── native-select.field.tsx # FieldNativeSelect
|
||||
├── checkbox.field.tsx # FieldCheckbox
|
||||
├── radio-group.field.tsx # FieldRadioGroup
|
||||
├── switch.field.tsx # FieldSwitch
|
||||
├── slider.field.tsx # FieldSlider
|
||||
├── range-slider.field.tsx # FieldRangeSlider
|
||||
├── rating.field.tsx # FieldRating
|
||||
├── color-input.field.tsx # FieldColorInput
|
||||
├── color-picker.field.tsx # FieldColorPicker
|
||||
├── pin-input.field.tsx # FieldPinInput
|
||||
├── json-input.field.tsx # FieldJsonInput
|
||||
├── autocomplete.field.tsx # FieldAutocomplete
|
||||
├── tags-input.field.tsx # FieldTagsInput
|
||||
├── chip-group.field.tsx # FieldChipGroup
|
||||
├── segmented-control.field.tsx # FieldSegmentedControl
|
||||
├── file-input.field.tsx # FieldFileInput
|
||||
└── rich-text.field.tsx # FieldRichTextEditor
|
||||
```
|
||||
|
||||
Each field file is a thin one-liner:
|
||||
|
||||
```tsx
|
||||
// fields/text-input.field.tsx
|
||||
import { TextInput, type TextInputProps } from '@mantine/core';
|
||||
import { withRHF } from '../withRHF';
|
||||
|
||||
export const FieldTextInput = withRHF<TextInputProps>('FieldTextInput', TextInput);
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Performance & Memoization
|
||||
|
||||
### Why `React.memo` + `useController`?
|
||||
|
||||
In enterprise ERP forms with **1500+ fields**, performance is critical:
|
||||
|
||||
| Technique | What it prevents | Cost |
|
||||
|---|---|---|
|
||||
| **`useController`** | Global form state re-renders — each field subscribes only to its own slice | ~0 (hook-level isolation) |
|
||||
| **`React.memo`** | Parent-driven re-renders (e.g., grid layout changes, tab switches) | O(n) shallow prop comparison (typically n < 10) |
|
||||
|
||||
Together, they achieve **O(1) render cost per keystroke** regardless of form size.
|
||||
|
||||
### When `React.memo` is NOT needed
|
||||
|
||||
For simple forms (< 50 fields), `React.memo` adds negligible overhead but provides no measurable benefit. However, since the HOC is used across the entire organization, the default-on strategy ensures correctness at scale without requiring per-form tuning.
|
||||
|
||||
---
|
||||
|
||||
## i18n Error Translation
|
||||
|
||||
The HOC supports three error message formats:
|
||||
|
||||
### 1. Plain String (default Zod behavior)
|
||||
|
||||
```tsx
|
||||
const schema = z.object({
|
||||
name: z.string().min(1, 'Name is required'),
|
||||
});
|
||||
// Error displayed: "Name is required"
|
||||
```
|
||||
|
||||
### 2. JSON i18n Payload (structured translation)
|
||||
|
||||
Encode Zod errors as JSON with a translation key:
|
||||
|
||||
```tsx
|
||||
const schema = z.object({
|
||||
name: z.string().min(3, JSON.stringify({
|
||||
key: 'validation:min_length',
|
||||
values: { min: 3 },
|
||||
})),
|
||||
});
|
||||
// Error displayed: t('validation:min_length', { min: 3 })
|
||||
// → "Minimum 3 characters" (from validation namespace)
|
||||
```
|
||||
|
||||
### 3. Translation Key String
|
||||
|
||||
If the raw error string matches a key in the `validation` namespace:
|
||||
|
||||
```tsx
|
||||
const schema = z.object({
|
||||
email: z.string().email('validation:invalid_email'),
|
||||
});
|
||||
// Error displayed: t('validation:invalid_email')
|
||||
// → "Please enter a valid email address"
|
||||
```
|
||||
|
||||
### Translation Resolution Chain
|
||||
|
||||
```
|
||||
error.message
|
||||
├── JSON.parse → { key, values }
|
||||
│ ├── t(key, { ...values, ns: 'validation' }) → translated ✓
|
||||
│ └── t(key, { ...values, ns: 'common' }) → translated ✓
|
||||
│ └── raw error.message (fallback) → displayed as-is
|
||||
├── i18n.exists(message, { ns: 'validation' })
|
||||
│ └── t(message, { ns: 'validation' }) → translated ✓
|
||||
└── raw string → displayed as-is
|
||||
```
|
||||
|
||||
### Setting up the `validation` namespace
|
||||
|
||||
Add validation translations to your locale files:
|
||||
|
||||
```json
|
||||
// packages/core-i18n/src/locales/en/validation.json
|
||||
{
|
||||
"validation": {
|
||||
"required": "This field is required",
|
||||
"min_length": "Minimum {{min}} characters",
|
||||
"max_length": "Maximum {{max}} characters",
|
||||
"invalid_email": "Please enter a valid email address"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Theme & Style Inheritance
|
||||
|
||||
The Form components **do NOT hardcode any styles**. All visual appearance flows from:
|
||||
|
||||
1. **`ThemeProvider`** — Wraps `MantineProvider` with brand colors, density tokens, and color scheme
|
||||
2. **Density tokens** — `compactDensity` / `standardDensity` set default `size` props on all inputs (e.g., `TextInput: { defaultProps: { size: 'sm' } }`)
|
||||
3. **Color scheme** — `forceColorScheme` on `MantineProvider` handles dark/light mode
|
||||
4. **CSS variables** — `theme.css` maps Mantine CSS variables to Tailwind tokens
|
||||
|
||||
This means:
|
||||
|
||||
```tsx
|
||||
// The FieldTextInput inherits compact sizing, brand colors, and dark mode
|
||||
// automatically — no additional configuration needed.
|
||||
<ThemeProvider colorScheme="dark" density="compact">
|
||||
<form>
|
||||
<FieldTextInput name="email" control={control} label="Email" />
|
||||
</form>
|
||||
</ThemeProvider>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Layer
|
||||
|
||||
To prevent over-engineering and package fatigue, we house the validation layer directly inside the UI package at `packages/ui/src/validators` rather than creating a separate `@repo/validation` package. This layer defines centralized Zod schemas that are pre-configured to output JSON-stringified i18n payloads.
|
||||
|
||||
### Writing a Centralized Validator
|
||||
|
||||
```tsx
|
||||
// packages/ui/src/validators/sample.validator.ts
|
||||
import { z } from 'zod';
|
||||
import { compose, emailValidator, minLength } from './registry.validator';
|
||||
|
||||
export const sampleValidator = z.object({
|
||||
email: compose(z.string(), emailValidator()),
|
||||
name: compose(z.string(), minLength(3, 'Nama')),
|
||||
});
|
||||
|
||||
export type SampleValidatorType = z.infer<typeof sampleValidator>;
|
||||
```
|
||||
|
||||
### Applying the Validator
|
||||
|
||||
When consuming these validators, use the `zodResolver` exported from `@repo/ui/form` and the validator from `@repo/ui/validators`. The Form components will automatically intercept the JSON payload, translate it using the `validation` namespace, and display the correct language to the user.
|
||||
|
||||
```tsx
|
||||
import { useForm, type SubmitHandler } from 'react-hook-form';
|
||||
import { zodResolver } from '@hookform/resolvers/zod';
|
||||
import { FieldTextInput } from '@repo/ui/form';
|
||||
import { sampleValidator, type SampleValidatorType } from '@repo/ui/validators';
|
||||
|
||||
function ExampleForm() {
|
||||
const { control, handleSubmit } = useForm<SampleValidatorType>({
|
||||
resolver: zodResolver(sampleValidator),
|
||||
defaultValues: { email: '', name: '' },
|
||||
});
|
||||
|
||||
const onSubmit: SubmitHandler<SampleValidatorType> = (data) => console.log(data);
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit(onSubmit)}>
|
||||
<FieldTextInput name="email" control={control} label="Email" />
|
||||
<FieldTextInput name="name" control={control} label="Name" />
|
||||
<button type="submit">Submit</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validator Bank Reference
|
||||
|
||||
The `registry.validator.ts` provides a set of pre-configured atomic validators returning modified Zod schemas that automatically emit translated JSON payloads.
|
||||
|
||||
### Available Atomic Validators
|
||||
|
||||
| Category | Validator | Target Type | Description |
|
||||
|---|---|---|---|
|
||||
| **Numeric** | `minValue(min, field?)` | `ZodNumber` | Minimum numeric value |
|
||||
| **Numeric** | `maxValue(max, field?)` | `ZodNumber` | Maximum numeric value |
|
||||
| **Numeric** | `rangeValue(min, max, field?)` | `ZodNumber` | Restricts value between `min` and `max` limits |
|
||||
| **Numeric** | `positiveNumber(field?)` | `ZodNumber` | Restricts to positive numbers |
|
||||
| **String** | `minLength(len, field?)` | `ZodString` | Minimum string character length |
|
||||
| **String** | `maxLength(len, field?)` | `ZodString` | Maximum string character length |
|
||||
| **String** | `rangeLength(min, max, field?)` | `ZodString` | Restricts string length between `min` and `max` bounds |
|
||||
| **Security** | `simplePassword(min)` | `ZodString` | Checks password string length bounds only |
|
||||
| **Security** | `complexPassword(min)` | `ZodString` | Enforces length, 1 uppercase, 1 lowercase, 1 number, and 1 special char |
|
||||
| **Technical** | `emailValidator()` | `ZodString` | Standard email format |
|
||||
| **Technical** | `phoneValidator()` | `ZodString` | Enforces Indonesian (+62) phone number format |
|
||||
|
||||
> [!WARNING]
|
||||
> Always distinguish between `rangeValue` (which bounds the actual numeric integer/float) and `rangeLength` (which bounds the amount of characters in a string).
|
||||
|
||||
### Composition Guide
|
||||
|
||||
Instead of manually chaining long `.min().max().regex()` methods, use the `compose()` helper utility to elegantly stack atomic validators onto a base primitive.
|
||||
|
||||
**Example: User Registration Password Field**
|
||||
|
||||
```tsx
|
||||
import { z } from 'zod';
|
||||
import { compose, required, minLength, complexPassword } from '@repo/ui/validators';
|
||||
|
||||
export const userRegistrationSchema = z.object({
|
||||
password: compose(
|
||||
z.string(),
|
||||
required('Password'),
|
||||
complexPassword(8)
|
||||
)
|
||||
});
|
||||
```
|
||||
|
||||
### Testing Validators
|
||||
|
||||
We enforce strict test coverage for our Validation Bank. If you add a new atomic validator to `registry.validator.ts`, you MUST add corresponding tests to `__tests__/registry.validator.test.ts`.
|
||||
|
||||
Tests must explicitly verify the JSON stringified i18n payload:
|
||||
|
||||
```typescript
|
||||
it('minValue() should enforce min', () => {
|
||||
const schema = compose(z.number(), minValue(10, 'Age'));
|
||||
const res = schema.safeParse(5);
|
||||
|
||||
expect(res.success).toBe(false);
|
||||
expect(res.error?.issues[0].message).toBe(
|
||||
JSON.stringify({ key: 'validation:min_val', values: { min: 10, field: 'Age' } })
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reactive Form Logic: useConditionalField
|
||||
|
||||
To decouple complex rendering side-effects from your component's root render function, the `@repo/ui/hooks` module provides `useConditionalField`. This hook automatically cleans up React Hook Form fields based on dynamic boolean conditions, enabling efficient micro-subscription architectures via `useWatch`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The hook exclusively uses a strict `UseConditionalFieldOptions` object signature. Legacy positional parameters are no longer supported to ensure strict typing and predictability across the monorepo.
|
||||
|
||||
### Core Modes
|
||||
|
||||
The hook supports two cleanup strategies defined by the `mode` parameter:
|
||||
|
||||
| Mode | Behavior | Use Case |
|
||||
|---|---|---|
|
||||
| `unregister` | Completely unmounts the field. Value is wiped. Key is removed from submission payload. | Hidden fields (e.g. Spouse Name if "Single" is checked). |
|
||||
| `reset` | Field stays active/disabled. Value is wiped. Error state is cleared. Key is sent in payload as empty/default. | Disabled or Cascading fields (e.g. Email Input if "Subscribe" is false, or resetting City when Province changes). |
|
||||
|
||||
### Hook Configuration
|
||||
|
||||
```tsx
|
||||
import { useForm, useWatch } from 'react-hook-form';
|
||||
import { useConditionalField } from '@repo/ui/hooks';
|
||||
|
||||
export function ExampleForm() {
|
||||
const { control, setValue, unregister, clearErrors } = useForm();
|
||||
|
||||
const userType = useWatch({ control, name: 'userType' });
|
||||
const newsletter = useWatch({ control, name: 'newsletter' });
|
||||
|
||||
// 1. Unregister Mode (Hidden Field)
|
||||
useConditionalField({
|
||||
condition: userType === 'CORPORATE',
|
||||
name: 'corporateTaxId',
|
||||
setValue,
|
||||
unregister,
|
||||
mode: 'unregister'
|
||||
});
|
||||
|
||||
// 2. Reset Mode (Visible but Disabled)
|
||||
useConditionalField({
|
||||
condition: newsletter === true,
|
||||
name: 'newsletterEmail',
|
||||
setValue,
|
||||
clearErrors,
|
||||
mode: 'reset'
|
||||
});
|
||||
|
||||
return <form>...</form>;
|
||||
}
|
||||
```
|
||||
|
||||
### Cascading Dropdowns & Reactivity
|
||||
|
||||
When dealing with cascading dependencies (e.g., Department -> Role), changing the parent dropdown should invalidate and reset the child dropdown.
|
||||
|
||||
You can accomplish this easily by supplying `mode: 'reset'` to `useConditionalField`. However, there is a **critical rendering caveat** with Mantine's `Select` (and similar complex visual inputs):
|
||||
|
||||
> [!WARNING]
|
||||
> **The Dynamic Key Trick:** Mantine components aggressively cache their internal visual text state. Even if `useConditionalField` perfectly resets the React Hook Form payload state to `''`, Mantine may still visually display the old, stale text on the screen.
|
||||
>
|
||||
> To fix this UI desync, you **must bind the parent dependency to the child component's `key` prop**. This forces React's reconciliation engine to completely unmount and remount the child DOM node, flushing Mantine's internal cache and guaranteeing perfect UI synchronization.
|
||||
|
||||
#### Master Example: Department to Role Cascade
|
||||
|
||||
```tsx
|
||||
import { useForm, useWatch } from 'react-hook-form';
|
||||
import { useConditionalField } from '@repo/ui/hooks';
|
||||
import { FieldSelect } from '@repo/ui/form';
|
||||
|
||||
export function DepartmentForm() {
|
||||
const { control, setValue, clearErrors } = useForm();
|
||||
|
||||
const department = useWatch({ control, name: 'department' });
|
||||
const role = useWatch({ control, name: 'role' });
|
||||
|
||||
// Derive available options based on the parent state
|
||||
const currentRoleOptions = department === 'IT'
|
||||
? [{ value: 'FRONTEND', label: 'Frontend' }, { value: 'BACKEND', label: 'Backend' }]
|
||||
: [];
|
||||
|
||||
// Determine if the currently selected role is still mathematically valid
|
||||
const isRoleValid = !role || (!!department && currentRoleOptions.some(opt => opt.value === role));
|
||||
|
||||
// 3. Reset Mode: Automatically wipes the field value in the RHF Payload if it becomes invalid
|
||||
useConditionalField({
|
||||
condition: isRoleValid,
|
||||
name: 'role',
|
||||
setValue,
|
||||
clearErrors,
|
||||
mode: 'reset',
|
||||
defaultValue: ''
|
||||
});
|
||||
|
||||
return (
|
||||
<form>
|
||||
<FieldSelect
|
||||
name="department"
|
||||
control={control}
|
||||
label="Department"
|
||||
data={[{ value: 'IT', label: 'Information Technology' }]}
|
||||
/>
|
||||
|
||||
{/* CRITICAL: We bind the department string to the key prop to force remounts on change */}
|
||||
<FieldSelect
|
||||
key={`role-select-${department}`}
|
||||
name="role"
|
||||
control={control}
|
||||
label="Role"
|
||||
disabled={!department}
|
||||
data={currentRoleOptions}
|
||||
/>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Object & Async Select Components
|
||||
|
||||
Mantine's native `Select` and `MultiSelect` are string-based: they store `string | null` and `string[]` respectively. In enterprise applications, we often need to store **full objects** (`T | null` or `T[]`) in RHF state — for example, a user object `{ id: '1', name: 'Alice', email: 'alice@co.com' }` rather than just `'1'`.
|
||||
|
||||
The **LocalSelect** and **AsyncSelect** engines bridge this gap by:
|
||||
1. Mapping `T[]` → `ComboboxItem[]` for Mantine rendering (via `valueKey` + `labelKey`/`renderLabel`)
|
||||
2. Building an O(1) reverse lookup map (`Map<string, T>`) for resolving string changes back to full objects
|
||||
3. Intercepting `onChange` to pass resolved objects to RHF
|
||||
|
||||
> [!IMPORTANT]
|
||||
> These components are **separate** from the native `FieldSelect` and `FieldMultiSelect`, which continue to work as simple string-based Mantine wrappers. Use `FieldLocalSelect`/`FieldAsyncSelect` only when you need to store full objects in RHF state.
|
||||
|
||||
### Single vs. Multi-Select Data Mapping
|
||||
|
||||
| Mode | Mantine Component | RHF Value | Mantine `value` Prop | `onChange` Payload |
|
||||
|---|---|---|---|---|
|
||||
| `multiple={false}` (default) | `<Select />` | `T \| null` | `string \| null` | `T \| null` |
|
||||
| `multiple={true}` | `<MultiSelect />` | `T[]` | `string[]` | `T[]` |
|
||||
|
||||
### FieldLocalSelect — Local Object Select
|
||||
|
||||
Accepts a static `data` array of objects. No async fetching.
|
||||
|
||||
#### Props
|
||||
|
||||
| Prop | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `options` | `T[]` | ✅ | Array of objects to select from |
|
||||
| `valueKey` | `keyof T & string` | ✅ | Property used as the unique identifier |
|
||||
| `labelKey` | `keyof T & string` | — | Property used as the display label |
|
||||
| `renderLabel` | `(item: T) => string` | — | Custom label renderer (overrides `labelKey`) |
|
||||
| `multiple` | `boolean` | — | Enable multi-select mode |
|
||||
| `filterOption` | `(item: T, ctx) => boolean` | — | Custom filter/exclusion logic |
|
||||
| `onSelect` | `(value: T \| T[] \| null) => void` | — | Side-effect callback on selection change |
|
||||
| `name` | `FieldPath` | ✅ | RHF field path |
|
||||
| `control` | `Control` | ✅ | RHF control object |
|
||||
| _...all Mantine Select/MultiSelect props_ | | | Passed through to the underlying component |
|
||||
|
||||
#### Usage Example
|
||||
|
||||
```tsx
|
||||
import { useForm } from 'react-hook-form';
|
||||
import { FieldLocalSelect } from '@repo/ui/form';
|
||||
|
||||
interface Department {
|
||||
id: string;
|
||||
name: string;
|
||||
code: string;
|
||||
}
|
||||
|
||||
const departments: Department[] = [
|
||||
{ id: '1', name: 'Engineering', code: 'ENG' },
|
||||
{ id: '2', name: 'Marketing', code: 'MKT' },
|
||||
{ id: '3', name: 'Finance', code: 'FIN' },
|
||||
];
|
||||
|
||||
function DepartmentForm() {
|
||||
const { control, handleSubmit } = useForm<{ department: Department | null }>({
|
||||
defaultValues: { department: null },
|
||||
});
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit((data) => console.log(data.department))}>
|
||||
<FieldLocalSelect<Department>
|
||||
name="department"
|
||||
control={control}
|
||||
label="Department"
|
||||
options={departments}
|
||||
valueKey="id"
|
||||
labelKey="name"
|
||||
searchable
|
||||
/>
|
||||
<button type="submit">Submit</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
// On submit: data.department = { id: '1', name: 'Engineering', code: 'ENG' }
|
||||
```
|
||||
|
||||
### FieldAsyncSelect — Async Paginated Object Select
|
||||
|
||||
Uses **Inversion of Control**: the component does NOT handle API calls directly. Instead, you provide a `loadOptions` callback. This supports REST, GraphQL, POST-based search, or any transport.
|
||||
|
||||
#### Props
|
||||
|
||||
| Prop | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `loadOptions` | `LoadOptionsFn<T>` | ✅ | Async callback: `(search, page, prevOptions) => Promise<{ options: T[], hasMore?: boolean }>` |
|
||||
| `defaultOptions` | `T[]` | — | Pre-loaded objects always present in dropdown (for edit forms) |
|
||||
| `debounceMs` | `number` | — | Search debounce delay (default: 300) |
|
||||
| `valueKey` | `keyof T & string` | ✅ | Property used as the unique identifier |
|
||||
| `labelKey` | `keyof T & string` | — | Property used as the display label |
|
||||
| `renderLabel` | `(item: T) => string` | — | Custom label renderer |
|
||||
| `multiple` | `boolean` | — | Enable multi-select mode |
|
||||
| `name` | `FieldPath` | ✅ | RHF field path |
|
||||
| `control` | `Control` | ✅ | RHF control object |
|
||||
| _...all Mantine Select/MultiSelect props_ | | | Passed through to the underlying component |
|
||||
|
||||
#### Paginated Example
|
||||
|
||||
```tsx
|
||||
import { useForm } from 'react-hook-form';
|
||||
import { FieldAsyncSelect, type LoadOptionsFn } from '@repo/ui/form';
|
||||
import { api } from '@/lib/api';
|
||||
|
||||
interface User {
|
||||
id: string;
|
||||
fullName: string;
|
||||
email: string;
|
||||
}
|
||||
|
||||
// The loadOptions callback is completely transport-agnostic
|
||||
const loadUsers: LoadOptionsFn<User> = async (search, page) => {
|
||||
const res = await api.get('/users', {
|
||||
params: { q: search, page, limit: 20 },
|
||||
});
|
||||
return {
|
||||
options: res.data.items,
|
||||
hasMore: res.data.hasNextPage,
|
||||
};
|
||||
};
|
||||
|
||||
function UserPickerForm() {
|
||||
const { control, handleSubmit } = useForm<{ user: User | null }>({
|
||||
defaultValues: { user: null },
|
||||
});
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit((data) => console.log(data.user))}>
|
||||
<FieldAsyncSelect<User>
|
||||
name="user"
|
||||
control={control}
|
||||
label="Assign User"
|
||||
loadOptions={loadUsers}
|
||||
valueKey="id"
|
||||
labelKey="fullName"
|
||||
placeholder="Search users..."
|
||||
/>
|
||||
<button type="submit">Submit</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### Non-Paginated Example
|
||||
|
||||
If your API returns all results at once, return `hasMore: false`:
|
||||
|
||||
```tsx
|
||||
const loadRoles: LoadOptionsFn<Role> = async (search) => {
|
||||
const roles = await api.get('/roles', { params: { q: search } });
|
||||
return { options: roles.data, hasMore: false };
|
||||
};
|
||||
```
|
||||
|
||||
#### Edit Form with `defaultOptions`
|
||||
|
||||
When editing an existing record, the default value's object may not appear in the first page of API results. Use `defaultOptions` to inject it:
|
||||
|
||||
```tsx
|
||||
function EditUserForm({ existingAssignment }: { existingAssignment: User }) {
|
||||
const { control } = useForm<{ user: User | null }>({
|
||||
defaultValues: { user: existingAssignment },
|
||||
});
|
||||
|
||||
return (
|
||||
<FieldAsyncSelect<User>
|
||||
name="user"
|
||||
control={control}
|
||||
label="Reassign User"
|
||||
loadOptions={loadUsers}
|
||||
valueKey="id"
|
||||
labelKey="fullName"
|
||||
defaultOptions={[existingAssignment]}
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
#### Multi-Select Async Example
|
||||
|
||||
```tsx
|
||||
function TagPickerForm() {
|
||||
const { control } = useForm<{ tags: Tag[] }>({
|
||||
defaultValues: { tags: [] },
|
||||
});
|
||||
|
||||
return (
|
||||
<FieldAsyncSelect<Tag>
|
||||
multiple
|
||||
name="tags"
|
||||
control={control}
|
||||
label="Tags"
|
||||
loadOptions={loadTags}
|
||||
valueKey="id"
|
||||
renderLabel={(tag) => `${tag.name} (${tag.count})`}
|
||||
/>
|
||||
);
|
||||
}
|
||||
// On submit: data.tags = [{ id: '1', name: 'React', count: 42 }, ...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Enterprise Performance Guidelines: Forms & Validation
|
||||
|
||||
When building large-scale ERP forms, seemingly trivial React or Zod patterns can catastrophically degrade performance at scale. Adhere strictly to the following optimizations.
|
||||
|
||||
### The "Unstable Default Value" Trap in Hooks
|
||||
|
||||
When creating custom form hooks (like `useConditionalField`), you often need to provide a fallback or default value. Passing an inline array or object as a `defaultValue` can trigger infinite render loops if it is included in a `useEffect` dependency array, because React's referential equality check fails on every render.
|
||||
|
||||
**Solution: The `useRef` Stabilization Pattern**
|
||||
|
||||
We resolve this by storing the `defaultValue` in a `useRef`. This allows the hook's cleanup logic to access the latest value without triggering the effect again:
|
||||
|
||||
```tsx
|
||||
// Inside useConditionalField.ts
|
||||
const defaultValueRef = useRef(defaultValue);
|
||||
|
||||
// Update ref on every render without triggering dependencies
|
||||
useEffect(() => {
|
||||
defaultValueRef.current = defaultValue;
|
||||
}, [defaultValue]);
|
||||
|
||||
// The main effect no longer depends on defaultValue
|
||||
useEffect(() => {
|
||||
if (!condition) {
|
||||
const targetValue = defaultValueRef.current !== undefined ? defaultValueRef.current : '';
|
||||
setValue(name, targetValue);
|
||||
}
|
||||
}, [condition, name, setValue]);
|
||||
```
|
||||
|
||||
### Zod Schema Performance: Avoid superRefine for Conditionals
|
||||
|
||||
For complex dynamic forms, developers often default to `.superRefine` or `.refine` to handle conditional validation (e.g., "Require Tax ID only if userType is Corporate").
|
||||
|
||||
**The Problem:** `superRefine` acts as an opaque callback. Zod cannot optimize it. In large forms, doing manual `.safeParse` inside a `superRefine` loop forces Zod to parse the entire tree continuously on every keystroke, leading to severe O(n) CPU spikes.
|
||||
|
||||
**The Solution:** Use declarative schema branching via `.and()`, `z.discriminatedUnion`, and `z.union`. These are statically analyzed by Zod and evaluated at native speed.
|
||||
|
||||
#### ❌ Bad: Manual Parsing (O(n) CPU Spike)
|
||||
|
||||
```tsx
|
||||
const badSchema = z.object({
|
||||
userType: z.enum(['PERSONAL', 'CORPORATE']),
|
||||
corporateTaxId: z.string().optional()
|
||||
}).superRefine((data, ctx) => {
|
||||
if (data.userType === 'CORPORATE') {
|
||||
// ⚠️ INCREDIBLY SLOW: Manual parsing inside refine loop
|
||||
const res = taxIdValidator.safeParse(data.corporateTaxId);
|
||||
if (!res.success) ctx.addIssue({ ...res.error.issues[0], path: ['corporateTaxId'] });
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
#### ✅ Good: Declarative Unions (O(1) Evaluation)
|
||||
|
||||
```tsx
|
||||
const goodSchema = z.object({
|
||||
userType: z.enum(['PERSONAL', 'CORPORATE']),
|
||||
corporateTaxId: z.string().optional()
|
||||
}).and(
|
||||
z.discriminatedUnion('userType', [
|
||||
z.object({ userType: z.literal('PERSONAL') }),
|
||||
z.object({ userType: z.literal('CORPORATE'), corporateTaxId: taxIdValidator })
|
||||
])
|
||||
);
|
||||
```
|
||||
|
||||
By stacking `.and(z.union([...]))` for independent conditionals (like `hasSpouse`, `newsletter`, etc.), you achieve lightning-fast, type-safe conditional validation without writing a single `superRefine` loop.
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Form
|
||||
|
||||
```tsx
|
||||
import { useForm, type SubmitHandler } from 'react-hook-form';
|
||||
import { FieldTextInput, FieldPasswordInput } from '@repo/ui/form';
|
||||
|
||||
type LoginForm = { email: string; password: string };
|
||||
|
||||
function LoginForm() {
|
||||
const { control, handleSubmit } = useForm<LoginForm>({
|
||||
defaultValues: { email: '', password: '' },
|
||||
});
|
||||
|
||||
const onSubmit: SubmitHandler<LoginForm> = (data) => {
|
||||
console.log(data);
|
||||
};
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit(onSubmit)}>
|
||||
<FieldTextInput name="email" control={control} label="Email" />
|
||||
<FieldPasswordInput name="password" control={control} label="Password" />
|
||||
<button type="submit">Login</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### With Zod Validation
|
||||
|
||||
```tsx
|
||||
import { z } from 'zod';
|
||||
import { useForm, type SubmitHandler } from 'react-hook-form';
|
||||
import { zodResolver } from '@hookform/resolvers/zod';
|
||||
import {
|
||||
FieldTextInput,
|
||||
FieldNumberInput,
|
||||
FieldSelect,
|
||||
FieldCheckbox,
|
||||
} from '@repo/ui/form';
|
||||
|
||||
const productSchema = z.object({
|
||||
name: z.string().min(1, {
|
||||
message: JSON.stringify({ key: 'validation:required', values: { field: 'Product Name' } })
|
||||
}),
|
||||
sku: z.string().regex(/^[A-Z]{3}-\d{4}$/, {
|
||||
message: JSON.stringify({ key: 'validation:invalid_format', values: { format: 'AAA-0000' } })
|
||||
}),
|
||||
price: z.number().min(0, {
|
||||
message: JSON.stringify({ key: 'validation:min_value', values: { min: 0 } })
|
||||
}),
|
||||
category: z.string().min(1, {
|
||||
message: JSON.stringify({ key: 'validation:required', values: { field: 'Category' } })
|
||||
}),
|
||||
isActive: z.boolean(),
|
||||
});
|
||||
|
||||
type ProductForm = z.infer<typeof productSchema>;
|
||||
|
||||
function ProductEditor() {
|
||||
const { control, handleSubmit } = useForm<ProductForm>({
|
||||
resolver: zodResolver(productSchema),
|
||||
defaultValues: {
|
||||
name: '',
|
||||
sku: '',
|
||||
price: 0,
|
||||
category: '',
|
||||
isActive: true,
|
||||
},
|
||||
});
|
||||
|
||||
const onSubmit: SubmitHandler<ProductForm> = (data) => console.log(data);
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit(onSubmit)}>
|
||||
<FieldTextInput name="name" control={control} label="Product Name" />
|
||||
<FieldTextInput name="sku" control={control} label="SKU" placeholder="ABC-1234" />
|
||||
<FieldNumberInput name="price" control={control} label="Price" min={0} prefix="$" />
|
||||
<FieldSelect
|
||||
name="category"
|
||||
control={control}
|
||||
label="Category"
|
||||
data={['Electronics', 'Clothing', 'Food']}
|
||||
/>
|
||||
<FieldCheckbox name="isActive" control={control} label="Active" />
|
||||
<button type="submit">Save Product</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Field Component
|
||||
|
||||
Use `withRHF` directly to wrap any Mantine component not included in the library:
|
||||
|
||||
```tsx
|
||||
import { DatePickerInput, type DatePickerInputProps } from '@mantine/dates';
|
||||
import { withRHF } from '@repo/ui/form';
|
||||
|
||||
export const FieldDatePicker = withRHF<DatePickerInputProps>(
|
||||
'FieldDatePicker',
|
||||
DatePickerInput,
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Reference
|
||||
|
||||
| Component | Mantine Source | Type | Notes |
|
||||
|---|---|---|---|
|
||||
| `FieldTextInput` | `TextInput` | Text | Standard text input |
|
||||
| `FieldPasswordInput` | `PasswordInput` | Text | Password with visibility toggle |
|
||||
| `FieldTextarea` | `Textarea` | Text | Multi-line text |
|
||||
| `FieldNumberInput` | `NumberInput` | Text | Numeric with increment/decrement |
|
||||
| `FieldJsonInput` | `JsonInput` | Text | JSON-formatted text |
|
||||
| `FieldPinInput` | `PinInput` | Text | PIN/OTP code input |
|
||||
| `FieldAutocomplete` | `Autocomplete` | Text | Text input with suggestions |
|
||||
| `FieldSelect` | `Select` | Selection | Single-value dropdown |
|
||||
| `FieldMultiSelect` | `MultiSelect` | Selection | Multi-value dropdown |
|
||||
| `FieldNativeSelect` | `NativeSelect` | Selection | Native `<select>` element |
|
||||
| `FieldTagsInput` | `TagsInput` | Selection | Free-form tag entry |
|
||||
| `FieldCheckbox` | `Checkbox` | Toggle | Boolean checkbox (uses `checked`) |
|
||||
| `FieldRadioGroup` | `Radio.Group` | Toggle | Radio button group |
|
||||
| `FieldSwitch` | `Switch` | Toggle | Boolean switch (uses `checked`) |
|
||||
| `FieldChipGroup` | `Chip.Group` | Toggle | Chip selection group (uses `Input.Wrapper`) |
|
||||
| `FieldSegmentedControl` | `SegmentedControl` | Toggle | Segmented control (uses `Input.Wrapper`) |
|
||||
| `FieldSlider` | `Slider` | Range | Single-value slider |
|
||||
| `FieldRangeSlider` | `RangeSlider` | Range | Dual-handle range slider |
|
||||
| `FieldRating` | `Rating` | Range | Star rating |
|
||||
| `FieldColorInput` | `ColorInput` | Color | Color picker with text input |
|
||||
| `FieldColorPicker` | `ColorPicker` | Color | Color picker only (uses `Input.Wrapper`) |
|
||||
| `FieldLocalSelect` | `Select / MultiSelect` | Selection | Stores full `T` or `T[]` object in RHF instead of string ID. Accepts static `options` array with `valueKey`/`labelKey` mapping. |
|
||||
| `FieldAsyncSelect` | `Select / MultiSelect` | Selection | Async paginated object select with IoC `loadOptions` callback. Supports search-keyed caching, `defaultOptions` for edit forms, and automatic pagination detection. |
|
||||
| `FieldFileInput` | `<FileInput />` | `File | File[] | null` |
|
||||
| `FieldRichTextEditor` | `@mantine/tiptap` | `string` (HTML) |
|
||||
|
||||
### Rich Text Editor (TipTap)
|
||||
The `FieldRichTextEditor` component integrates `@mantine/tiptap` directly with React Hook Form. It safely stores the Editor's HTML output directly into the RHF state as a `string`. Because TipTap is an uncontrolled editor natively, this field uses a specialized `useController` wrapper that automatically syncs bidirectional updates (e.g., calling `editor.commands.setContent(field.value)` when the form is reset or async default values arrive).
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Tests are located in `src/components/Form/__tests__/` and can be run via:
|
||||
|
||||
```bash
|
||||
cd packages/ui && pnpm test
|
||||
```
|
||||
|
||||
The test suite covers:
|
||||
|
||||
- **`withRHF.test.tsx`** (8 tests) — Core HOC behavior: rendering, value binding, input mutation, error display, i18n translation, fallback behavior, displayName, prop forwarding
|
||||
- **`text-input.field.test.tsx`** (4 tests) — FieldTextInput integration with Zod validation, error display/clearing, and full submission flow
|
||||
- **`checkbox.field.test.tsx`** (4 tests) — FieldCheckbox boolean toggle, checked state, RHF submission, and Zod required validation
|
||||
|
||||
All tests use `@testing-library/react` with mocked `@repo/core-i18n` and a `window.matchMedia` polyfill for jsdom compatibility with Mantine v8.
|
||||
@@ -0,0 +1,80 @@
|
||||
# @repo/ui — Shared UI Component Library
|
||||
|
||||
The centralized UI component library for the monorepo. Provides consistent design primitives, system pages, and **a comprehensive Form UI Library** for building enterprise-grade forms.
|
||||
|
||||
## Features
|
||||
|
||||
- **Mantine v8** components re-exported with unified theming
|
||||
- **ThemeProvider** with dark/light mode, brand colors, and density modes (compact/standard)
|
||||
- **Design tokens** — Colors, typography, radius, spacing, shadows mapped between Mantine and Tailwind
|
||||
- **System pages** — Pre-built 404, 403, Maintenance, and Coming Soon pages
|
||||
- **Form UI Library** — 22 RHF-connected Mantine form components with Zod validation and i18n error translation
|
||||
|
||||
## Exports
|
||||
|
||||
| Entry Point | Path | Description |
|
||||
|---|---|---|
|
||||
| `@repo/ui/components` | `./src/components/index.ts` | All components (Mantine re-exports + system pages + Form fields) |
|
||||
| `@repo/ui/form` | `./src/components/Form/index.ts` | Form field components, `withRHF` factory, RHF/Zod re-exports |
|
||||
| `@repo/ui/hooks` | `./src/hooks/index.ts` | Mantine hooks re-export |
|
||||
| `@repo/ui/provider` | `./src/provider/index.ts` | `ThemeProvider` with color scheme and density controls |
|
||||
| `@repo/ui/theme.css` | `./src/theme.css` | Base CSS with Mantine → Tailwind token mapping |
|
||||
|
||||
## 📋 Form UI Library
|
||||
|
||||
> **Full Documentation**: [FORM-COMPONENTS.md](./FORM-COMPONENTS.md)
|
||||
|
||||
The Form UI Library wraps **all 22 applicable Mantine form components** with React Hook Form via a single `withRHF()` HOC factory. Key features:
|
||||
|
||||
- **`useController` micro-subscriptions** — O(1) render cost per keystroke, even in 1500+ field ERP forms
|
||||
- **`React.memo` wrapper** — Prevents parent-driven cascade re-renders
|
||||
- **Zod + i18n error translation** — JSON error payloads are auto-parsed and translated via `@repo/core-i18n`
|
||||
- **Zero hardcoded styles** — All components inherit the active `ThemeProvider` configuration
|
||||
- **`Field` prefix naming** — `FieldTextInput`, `FieldSelect`, etc. to avoid collisions with native Mantine exports
|
||||
|
||||
### Quick Start
|
||||
|
||||
```tsx
|
||||
import { z } from 'zod';
|
||||
import { useForm, zodResolver, FieldTextInput, FieldSelect } from '@repo/ui/form';
|
||||
|
||||
const schema = z.object({
|
||||
name: z.string().min(1, 'Name is required'),
|
||||
role: z.string().min(1, 'Please select a role'),
|
||||
});
|
||||
|
||||
function UserForm() {
|
||||
const { control, handleSubmit } = useForm({
|
||||
resolver: zodResolver(schema),
|
||||
defaultValues: { name: '', role: '' },
|
||||
});
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit(console.log)}>
|
||||
<FieldTextInput name="name" control={control} label="Name" />
|
||||
<FieldSelect
|
||||
name="role"
|
||||
control={control}
|
||||
label="Role"
|
||||
data={['Admin', 'Editor', 'Viewer']}
|
||||
/>
|
||||
<button type="submit">Save</button>
|
||||
</form>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Scripts
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pnpm test` | Run unit tests (Vitest) |
|
||||
| `pnpm test:watch` | Run tests in watch mode |
|
||||
| `pnpm lint` | Run ESLint |
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@mantine/core` v8, `@mantine/hooks` v8
|
||||
- `react-hook-form` v7, `@hookform/resolvers` v5, `zod` v3
|
||||
- `@repo/core-i18n` (workspace)
|
||||
- `tailwindcss` v4, `tailwind-variants`, `tailwind-merge`
|
||||
@@ -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.
|
||||
@@ -1,46 +0,0 @@
|
||||
import type { Meta, StoryObj } from '@storybook/react';
|
||||
import { Button } from '@repo/ui';
|
||||
|
||||
const meta: Meta<typeof Button> = {
|
||||
component: Button,
|
||||
argTypes: {
|
||||
type: {
|
||||
control: { type: 'radio' },
|
||||
options: ['button', 'submit', 'reset'],
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
export default meta;
|
||||
|
||||
type Story = StoryObj<typeof Button>;
|
||||
|
||||
/*
|
||||
*👇 Render functions are a framework specific feature to allow you control on how the component renders.
|
||||
* See https://storybook.js.org/docs/react/api/csf
|
||||
* to learn how to use render functions.
|
||||
*/
|
||||
export const Primary: Story = {
|
||||
render: (props) => (
|
||||
<Button
|
||||
{...props}
|
||||
onClick={(): void => {
|
||||
// eslint-disable-next-line no-alert -- alert for demo
|
||||
alert('Hello from Turborepo!');
|
||||
}}
|
||||
>
|
||||
Hello
|
||||
</Button>
|
||||
),
|
||||
name: 'Button',
|
||||
args: {
|
||||
children: 'Hello',
|
||||
type: 'submit',
|
||||
style: {
|
||||
color: 'blue',
|
||||
border: '1px solid gray',
|
||||
padding: 10,
|
||||
borderRadius: 10,
|
||||
},
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,7 @@
|
||||
export default {
|
||||
vite: {
|
||||
optimizeDeps: {
|
||||
include: ['@repo/ui', 'mermaid', 'dayjs']
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
import { withMermaid } from 'vitepress-plugin-mermaid'
|
||||
|
||||
const baseConfig = withMermaid(
|
||||
defineConfig({
|
||||
title: "Test",
|
||||
})
|
||||
);
|
||||
|
||||
console.log("Before:", baseConfig.vite.optimizeDeps.include);
|
||||
baseConfig.vite.optimizeDeps.include = baseConfig.vite.optimizeDeps.include.filter(
|
||||
(dep) => !['@braintree/sanitize-url', 'debug', 'cytoscape-cose-bilkent', 'cytoscape'].includes(dep)
|
||||
);
|
||||
console.log("After:", baseConfig.vite.optimizeDeps.include);
|
||||
@@ -1,4 +0,0 @@
|
||||
import { defineConfig } from 'vite';
|
||||
import react from '@vitejs/plugin-react';
|
||||
|
||||
export default defineConfig({ plugins: [react()] });
|
||||
Reference in New Issue
Block a user