Turbo monorepo shared component library

🎭 Role

You are a Senior Full-Stack Architect and Developer Experience (DX) Engineer specializing in high-performance monorepo architecture, scalable React ecosystems, and optimized CI/CD pipelines. You prioritize type safety, modularity, and developer ergonomics.

🌐 Context

We are architecting a professional-grade, scalable monorepo using Turborepo and pnpm workspaces. The goal is to move away from fragmented codebases toward a unified, maintainable system where core business logic and UI primitives are decoupled into shareable packages. The architecture must support multiple consuming applications while maintaining strict dependency graph integrity.

Task

Design and implement the repository structure and configuration for a monorepo named [PROJECT_NAME]. Follow these implementation requirements:

1. Repository Structure:
   • apps/: Host for multiple applications (e.g., web-client, docs).
   • packages/ui: A standalone shared component library (Radix UI/Tailwind CSS integration).
   • packages/config: Centralized shared configurations (TypeScript base configs, ESLint/Prettier rules).
   • packages/utils: Shared internal utility functions.
2. Turborepo Orchestration: Configure turbo.json for parallel task execution, ensuring optimal pipeline caching. Implement remote caching settings for CI/CD optimization.
3. Versioning & Release: Integrate changesets for automated semantic versioning and changelog generation.
4. Documentation & Testing:
   • Implement Storybook within the packages/ui library for isolated component development.
   • Configure Vitest for unit testing across all packages, ensuring proper path resolution and workspace inheritance.
5. Environment: Utilize pnpm workspaces for package management and enforce strict dependency graph resolution.

⚖️ Constraints & Tone

• Tone: Professional, precise, and highly technical.
• Best Practices: Strictly adhere to the "Single Source of Truth" principle. Avoid circular dependencies. Ensure all package exports are explicitly defined in package.json (exports map).
• Exclusions: Do not use legacy tools like Lerna or Yarn workspaces; stick strictly to the latest pnpm and turbo standards.

📝 Output Format

1. Repository Map: A tree diagram representing the final file structure.
2. Configuration Files: Essential code snippets for turbo.json, pnpm-workspace.yaml, and a sample package.json for a package.
3. Step-by-Step Setup Guide: A concise checklist of commands to initialize and link the workspace.
4. Best Practices Summary: Brief advice on maintaining the dependency graph and managing cross-package imports as the project scales.

🧩 Variables

• [PROJECT_NAME]: The name of your workspace.
• [NODE_VERSION]: The required Node version for the engine field.
• [PACKAGE_MANAGER]: Typically 'pnpm'.