Frontend Monorepo Architecture

You are a frontend platform engineer who has architected monorepo setups for large organizations managing multiple applications and shared libraries from a single repository. Create a comprehensive monorepo architecture for the following project.

Project Details:
Organization Size: [STARTUP/MID-SIZE/ENTERPRISE]
Number of Applications: [COUNT OF APPS]
Shared Libraries: [COMPONENT LIBRARY/UTILS/CONFIG/ALL]
Monorepo Tool: [NX/TURBOREPO/LERNA/PNPM WORKSPACES/NONE YET]
Package Manager: [PNPM/YARN/NPM]
CI/CD Platform: [GITHUB ACTIONS/GITLAB CI/JENKINS/CIRCLECI]

Section 1 - Repository Structure and Package Organization:
Define the top-level directory structure separating applications in an apps directory from shared packages in a packages directory with clear categories for UI components, utility libraries, configuration presets, and type definitions. Establish the package naming convention using an organization scope like @org/package-name that prevents naming conflicts with public npm packages and communicates ownership. Create the package boundary rules specifying which packages may depend on which other packages using a dependency graph that prevents circular dependencies and maintains a clear hierarchy from leaf packages with no internal dependencies to application packages at the top. Specify the shared configuration approach for TypeScript, ESLint, Prettier, and testing frameworks using a base configuration package that all applications and libraries extend ensuring consistency across the monorepo. Address the internal package versioning strategy choosing between fixed versioning where all packages share the same version number and independent versioning where each package has its own version with justification based on release coordination needs.

Section 2 - Build System and Task Orchestration:
Define the build orchestration setup using Turborepo or Nx to run build, test, lint, and type-check tasks across packages respecting dependency order and caching results to avoid rebuilding unchanged packages. Create the remote caching configuration that shares build cache across developer machines and CI runners so a package built by one developer does not need to be rebuilt by another or by CI. Establish the affected command strategy that determines which packages are affected by a code change and only runs tasks for those packages rather than the entire monorepo, dramatically reducing CI times for focused changes. Specify the dependency graph visualization and validation ensuring the build tool maintains an accurate dependency graph and can detect circular dependencies, missing peer dependencies, and packages that import from other packages without declaring the dependency. Address the build pipeline configuration defining task dependencies so that shared libraries build before the applications that depend on them and type checking runs after compilation to have accurate type information.

Section 3 - Shared Package Development:
Define the shared component library package structure including the component source files, the build output configuration for both ESM and CJS formats, the TypeScript declaration file generation, and the package.json exports field for proper module resolution. Create the internal package consumption approach choosing between building packages to a dist folder that consumers import from or using TypeScript path aliases that reference source files directly for faster development feedback without a build step. Establish the package development workflow including how developers run a shared package in watch mode alongside an application that consumes it enabling real-time development across package boundaries. Specify the breaking change management process for shared packages including how changes are proposed, reviewed, and communicated to consuming applications and how codemods or migration scripts are provided to ease adoption. Address the package extraction strategy for when an internal shared package should be published to a private or public npm registry for use outside the monorepo.

Section 4 - Dependency Management:
Define the dependency hoisting strategy using pnpm workspaces that prevent phantom dependencies where a package accidentally imports a dependency installed by another package or choosing Yarn with the nohoist configuration for packages that need isolated dependencies. Create the dependency version synchronization approach ensuring all packages in the monorepo use the same version of shared dependencies like React, TypeScript, and testing libraries using a root package.json or Syncpack for version alignment. Establish the dependency update workflow using Renovate or Dependabot configured for the monorepo to group related dependency updates, run affected tests, and create reviewable pull requests for dependency upgrades. Specify the peer dependency management for shared packages that need to be compatible with the React or framework version of the consuming application without bundling a duplicate copy of the framework. Address the external dependency audit process for evaluating new dependencies including bundle size impact, maintenance status, type safety, and whether the dependency would affect all packages or just specific applications.

Section 5 - CI/CD Pipeline Architecture:
Design the CI pipeline that maximizes parallelism and caching running affected tests, lint checks, type checks, and builds only for packages impacted by the current pull request. Create the deployment pipeline for multiple applications specifying how each application deploys independently when its code or its dependencies change, how to handle coordinated deployments when a shared library change affects multiple applications, and how to manage different deployment environments per application. Establish the pull request workflow including required checks that must pass before merging, the CODEOWNERS configuration that routes reviews to the appropriate team based on which packages are changed, and the branch protection rules. Specify the preview deployment strategy for applications including how to deploy preview environments for pull requests using Vercel, Netlify, or a custom solution and how shared library changes generate preview deployments of all affected applications. Address the release management approach for shared packages including changelog generation from conventional commits, version bumping automation, and the publish pipeline for packages distributed to a registry.

Section 6 - Team Workflow and Governance:
Define the code ownership model mapping each package to its responsible team using CODEOWNERS files and establishing the review requirements when a change crosses package boundaries requiring approval from both the authoring team and the consuming team. Create the contribution guidelines for the monorepo covering how to add a new package, how to add a new application, how to modify shared packages, and how to resolve dependency conflicts between packages. Establish the developer onboarding process including how new developers set up the monorepo locally, which commands to run, how to navigate the repository structure, and how to understand the dependency relationships between packages. Specify the monorepo maintenance tasks including periodic dependency updates, build cache pruning, unused package identification, and migration tooling for moving code between packages as organizational structure evolves. Address the scaling considerations for the monorepo including how to handle growing clone times, how to use sparse checkout for developers who only work on specific packages, and when a monorepo might need to be split into separate repositories.