trackgo-fe/README.md

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

.
├── 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:

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):

rm -rf node_modules **/*/node_modules .turbo **/*/.turbo dist **/*/dist

---

📝 License

This project is private and proprietary.