# Frontend Monorepo Template

![Turborepo](https://img.shields.io/badge/Turborepo-2.7.2-red?style=flat\&logo=turborepo)
![pnpm](https://img.shields.io/badge/pnpm-8.15.6-orange?style=flat\&logo=pnpm)
![Node.js](https://img.shields.io/badge/Node.js-v24.11.1-green?style=flat\&logo=nodedotjs)
![Vite](https://img.shields.io/badge/Vite-Bundler-blue?style=flat\&logo=vite)
![React](https://img.shields.io/badge/React-Framework-cyan?style=flat\&logo=react)
![TypeScript](https://img.shields.io/badge/TypeScript-Language-blue?style=flat\&logo=typescript)
![Vitest](https://img.shields.io/badge/Vitest-Testing-green?style=flat\&logo=vitest)

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**.