335 lines
14 KiB
Markdown
335 lines
14 KiB
Markdown
# Frontend Monorepo Template
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A **scalable, enterprise-ready Web & Desktop monorepo** built with **Turborepo**, **pnpm**, **Vite**, and **Electron**.
|
|
This repository is designed for long-term maintainability, featuring:
|
|
|
|
* Shared logic and UI libraries
|
|
* Centralized tooling configuration
|
|
* Turbo-powered task orchestration and caching
|
|
* Native desktop distribution with auto-updates
|
|
* Dedicated documentation & component playground using Storybook
|
|
|
|
---
|
|
|
|
## ๐ 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 (Storybook)
|
|
โ
|
|
โโโ 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
|
|
```
|
|
|
|
---
|
|
|
|
## ๐ 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 **Storybook** for UI development (strictly at `http://localhost:6006`) |
|
|
| `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 [AUTO_UPDATER.md](apps/desktop/docs/AUTO_UPDATER.md) for details.
|
|
|
|
> [!NOTE]
|
|
> **Cross-Compilation**: It is highly recommended to build for Windows on a Windows machine and for macOS on a Mac. Cross-compilation (e.g., building `.dmg` on Linux) may fail due to platform-specific toolchain dependencies. Use a CI matrix strategy (e.g., GitHub Actions with `runs-on: [macos-latest, windows-latest, ubuntu-latest]`) for multi-platform releases.
|
|
|
|
|
|
---
|
|
|
|
## ๐ฆ 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
|
|
|
|
**Key Capabilities**:
|
|
|
|
| Feature | Description |
|
|
|---|---|
|
|
| ๐จ๏ธ Native Printing | Silent and direct printing via secure IPC bridge |
|
|
| ๐ Auto-Updates | Background downloads via GitHub Releases (switchable to S3) |
|
|
| ๐ Secure IPC Bridge | `contextIsolation: true`, `nodeIntegration: false`, `sandbox: true` |
|
|
| ๐ Custom Protocol | `app://` serves static files with SPA routing fallback to `index.html` |
|
|
| ๐ก๏ธ CORS Bypass | Transparent Origin header rewriting for cloud API calls |
|
|
|
|
**Desktop Documentation**:
|
|
|
|
| Document | Contents |
|
|
|---|---|
|
|
| [CONFIGURATION.md](apps/desktop/docs/CONFIGURATION.md) | Target app switching, `app://` protocol internals, HashRouter fallback |
|
|
| [AUTO_UPDATER.md](apps/desktop/docs/AUTO_UPDATER.md) | Release workflow, CI/CD variables, provider switching, code signing |
|
|
| [IPC_ARCHITECTURE.md](apps/desktop/docs/IPC_ARCHITECTURE.md) | Security model, Three-Step Bridge pattern, extending native features |
|
|
|
|
---
|
|
|
|
### 3. `apps/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
|
|
|
|
**Tech Stack**:
|
|
|
|
* React
|
|
* Vite
|
|
* TypeScript
|
|
* Tailwind CSS v4
|
|
|
|
---
|
|
|
|
### 4. `apps/docs-dev` (Storybook)
|
|
|
|
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
|
|
|
|
---
|
|
|
|
### 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.
|
|
|
|
* Consumed by `apps/web`, `apps/landing`, and any future workspace
|
|
* Centralizes all `@grafana/faro-*` and `@opentelemetry/*` dependencies
|
|
* Provides plug-and-play telemetry via `initTelemetry()` + `faroAdapter`
|
|
|
|
**Tech Stack**:
|
|
|
|
* Axios (isolated instances, zero singleton pollution)
|
|
* Grafana Faro (RUM, Logs, Error tracking)
|
|
* OpenTelemetry (custom spans, distributed tracing)
|
|
* TypeScript (strict types, module augmentation)
|
|
|
|
**Key Capabilities**:
|
|
|
|
| Feature | Description |
|
|
|---|---|
|
|
| ๐ญ HTTP Client Factory | `createHttpClient()` โ per-app isolated Axios instances with interceptor hooks |
|
|
| ๐ก Faro/Loki Baseline | Every request automatically pushes structured logs with `module.key` and `module.action` |
|
|
| ๐ฏ Custom Spans (Opt-In) | `telemetryContext.customSpanName` creates explicit OTel spans visible in Grafana Tempo |
|
|
| ๐ก๏ธ Error Normalization | `ApiError.fromAxiosError()` โ structured, serializable error codes for all failure modes |
|
|
| ๐ฆ Data Services Engine | `CommonRemoteDataServices` โ full CRUD + lifecycle operations with zero boilerplate |
|
|
|
|
**Documentation**:
|
|
|
|
| Document | Contents |
|
|
|---|---|
|
|
| [README.md](packages/core-api/README.md) | Architecture, HTTP client setup, observability strategy, data services, app integration guide |
|
|
|
|
---
|
|
|
|
### 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`.
|
|
|
|
**Documentation**: [README.md](packages/core-storage/README.md)
|
|
|
|
---
|
|
|
|
### 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.
|
|
|
|
**Key Capabilities**:
|
|
|
|
| Feature | Description |
|
|
|---|---|
|
|
| ๐ Hybrid Namespaces | Centralized `common` corpus + lazy-loaded feature dictionaries. |
|
|
| ๐ก๏ธ Strict Typings | Native TS autocomplete for nested paths (e.g., `header.title`) via module augmentation. |
|
|
| ๐ Safe Backend Sync | `changeLanguage` accepts a `syncCallback` with built-in rollback if the API fails. |
|
|
| ๐ข Tenant Overrides | `applyTenantOverrides` performs a partial deep-merge to selectively override terminology. |
|
|
|
|
**Documentation**: [README.md](packages/core-i18n/README.md)
|
|
|
|
---
|
|
|
|
### 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.
|
|
|
|
**Key Capabilities**:
|
|
|
|
| Feature | Description |
|
|
|---|---|
|
|
| ๐งฉ Zero Coupling | Publishers and subscribers interact via blind events, eliminating direct module imports and circular dependencies. |
|
|
| โก Extreme Performance | Enables targeted DOM updates for high-frequency data streams (e.g., WebSockets) without re-rendering parent components. |
|
|
| ๐งน Memory Safety | Native `useAppEvent` hook automatically unsubscribes on component unmount, preventing SPA memory leaks. |
|
|
| ๐ก๏ธ Strict Contracts | Centralized `events.registry.ts` enforces payload shapes via TypeScript, ensuring cross-module data safety. |
|
|
|
|
**Documentation**: [README.md](packages/core-events/README.md)
|
|
|
|
---
|
|
|
|
### 9. `packages/utils`
|
|
|
|
Shared business logic and reusable utility modules that can be consumed across multiple applications. Fully tested using Vitest.
|
|
|
|
This package is intended to hold non-UI, cross-cutting logic such as date/time handling, security helpers, and other common utilities. It is designed to be framework-agnostic, predictable, and easy to extend as the system evolves.
|
|
|
|
---
|
|
|
|
### 10. `packages/ui`
|
|
|
|
Shared UI component library (Buttons, Inputs, Cards, Layouts).
|
|
|
|
* Ensures consistent design across all applications
|
|
* Designed to be consumed by both web apps and Storybook
|
|
|
|
---
|
|
|
|
### 11. `packages/configs`
|
|
|
|
Single source of truth for tooling configuration.
|
|
|
|
* **eslint-config**: Shared ESLint rules (React, libraries, Storybook)
|
|
* **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
|
|
```
|
|
|
|
---
|
|
|
|
## ๐ License
|
|
|
|
This project is **private and proprietary**.
|