161 lines
5.1 KiB
Markdown
161 lines
5.1 KiB
Markdown
# Frontend Monorepo Template
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A **scalable, enterprise-ready frontend monorepo template** built with **Turborepo**, **pnpm**, and **Vite**.
|
|
This repository is designed for long-term maintainability, featuring:
|
|
|
|
* Shared logic and UI libraries
|
|
* Centralized tooling configuration
|
|
* Turbo-powered task orchestration and caching
|
|
* 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)
|
|
│ └── docs-dev/ # Component Documentation & Playground (Storybook)
|
|
│
|
|
├── packages/
|
|
│ ├── 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**: `v24.11.1`
|
|
* **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** (usually at `http://localhost:5173`) |
|
|
| `pnpm dev:docs-dev` | Start **Storybook** for UI development (usually at `http://localhost:6006`) |
|
|
|
|
### Building & Quality
|
|
|
|
| Command | Description |
|
|
| --------------------- | --------------------------------------------- |
|
|
| `pnpm build` | Build all apps and packages using Turbo cache |
|
|
| `pnpm build:web` | Build only the web application |
|
|
| `pnpm build:docs-dev` | Build only the docs-dev application |
|
|
| `pnpm test` | Run unit tests (Vitest) across all packages |
|
|
| `pnpm lint` | Run ESLint across the workspace |
|
|
| `pnpm format` | Format code using Prettier |
|
|
|
|
---
|
|
|
|
## 📦 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/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
|
|
|
|
---
|
|
|
|
### 3. `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.
|
|
|
|
---
|
|
|
|
### 4. `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
|
|
|
|
---
|
|
|
|
### 5. `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
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 License
|
|
|
|
This project is **private and proprietary**.
|