Monorepo Structure Overview

This document provides a comprehensive overview of the Next.js monorepo structure, explaining the organization, purpose, and relationships between different packages and applications.

Repository Overview

The nextjs-web monorepo is organized using pnpm workspaces and Turbo for efficient package management and build orchestration. The repository follows a standard monorepo pattern with apps/ and packages/ directories.

Key Technologies

Package Manager: pnpm v9.1.1
Build System: Turbo v2.4.4
Runtime: Node.js v20.18
Framework: Next.js v15.2
Language: TypeScript v5.8
Container: Red Hat Enterprise Linux 9.5

Directory Structure

/home/
├── nextjs-web/              # Monorepo root directory
│   ├── apps/                # Application packages
│   ├── packages/            # Shared library packages
│   ├── package.json         # Root package configuration
│   ├── pnpm-workspace.yaml  # Workspace configuration
│   ├── turbo.json          # Turbo build configuration
│   ├── biome.jsonc         # Code formatting and linting
│   └── vercel.json         # Vercel deployment configuration
└── schwab-scripts/          # Container setup and maintenance scripts
    ├── setup-container.sh   # Main setup orchestrator
    ├── setup-env-git.sh     # Git environment configuration
    ├── setup-env-pnpm.sh    # PNPM and registry setup
    ├── setup-pull-repos.sh  # Repository cloning and dependencies
    ├── start-container.sh    # Container startup script
    ├── kill.sh              # Port cleanup utility
    └── git-hooks/           # Git quality gates
        ├── pre-commit.hook  # Branch name validation
        └── pre-push.hook    # Quality checks (lint, test, build)

Applications (`apps/`)

The apps/ directory contains all deployable applications. Each application is a complete Next.js project with its own configuration, dependencies, and build process.

Core Web Applications

Application	Description	Port	Purpose
www.schwab.com	Main public website	3000	Primary marketing and informational site
client.schwab.com	Client portal application	3001	Authenticated client interface
nextapi.schwab.com	API services	-	Backend API services
nexttools.schwab.com	Internal tools	-	Development and administrative tools

Supporting Applications

Application	Description	Port	Purpose
client-central	Client management system	-	Central client management interface
meganav-mfe	Mega navigation micro-frontend	-	Shared navigation component
storybook	Component library documentation	6006	UI component catalog and documentation
docs	Technical documentation	-	Developer documentation (this site)
beacon-docs	Design system documentation	-	Beacon design system documentation (Docusaurus)

Content Management

Application	Description	Purpose
sanity-studio	Sanity CMS admin interface	Content management system
sanity-next	Sanity CMS demo Next.js app	POC/testing application for Sanity integration

Shared Packages (`packages/`)

The packages/ directory contains reusable libraries and utilities shared across applications. These packages follow the @schwab/* naming convention.

Core Packages

Package	Purpose	Used By
@schwab/ui	React component library	All frontend applications
@schwab/fetch	HTTP client utilities	All applications requiring API calls
@schwab/utilities	Common utility functions	All applications
@schwab/security	Security utilities and middleware	Applications handling authentication

Configuration Packages

Package	Purpose	Description
tsconfig	TypeScript configurations	Base TypeScript configs for consistency
twconfig	Tailwind CSS configurations	Shared Tailwind configurations
test	Testing utilities	Common test setup and utilities

Development Packages

Package	Purpose	Description
cli	Command-line tools	Development and build utilities
mock-data	Test data and mocks	Shared mock data for testing
processors	Data processing utilities	Content and data transformation
transformer	Code transformation utilities	Build-time transformations
schema	Data schemas and validation	Shared data structures with Zod
server-actions	Next.js server actions	Shared server-side logic

Build System Architecture

Turbo Configuration

The monorepo uses Turbo for efficient builds with the following key features:

Dependency-aware builds: "dependsOn": ["^build"]
Incremental builds: Only rebuilds changed packages
Parallel execution: Concurrent task execution across packages
Caching: Build artifacts are cached for faster subsequent builds

Package Scripts

Common scripts available across the monorepo:

# Development
pnpm dev                    # Start all applications
pnpm dev-www               # Start www.schwab.com only
pnpm dev-client            # Start client.schwab.com only
pnpm dev-storybook         # Start Storybook only

# Building
pnpm build                 # Build all applications
pnpm build-www             # Build www.schwab.com only
pnpm build-client          # Build client.schwab.com only

# Testing and Quality
pnpm test                  # Run all tests
pnpm lint                  # Run linting
pnpm type-check            # TypeScript type checking
pnpm conformance           # Code conformance checks

Dependency Management

Workspace Dependencies

Packages within the monorepo reference each other using the workspace:* protocol:

{
  "dependencies": {
    "@schwab/ui": "workspace:*",
    "@schwab/fetch": "workspace:*",
    "@schwab/utilities": "workspace:*"
  }
}

Version Overrides

The root package.json includes pnpm overrides to ensure consistent versions:

{
  "pnpm": {
    "overrides": {
      "@types/react": "^19.0.12",
      "@types/react-dom": "^19.0.4"
    }
  }
}

Development Workflow

Container Environment Setup

The monorepo includes automated setup scripts located in /home/schwab-scripts that handle the initial development environment configuration:

Setup Process

Container Initialization: setup-container.sh orchestrates the entire setup
Git Configuration: setup-env-git.sh configures Git with corporate SSL and authentication
Package Manager Setup: setup-env-pnpm.sh configures pnpm for internal registries
Repository Cloning: setup-pull-repos.sh clones the monorepo and installs dependencies
Quality Gates: Git hooks are installed for automated code quality checks

Corporate Integration Features

Proxy Support: Automatic configuration for ZScaler and BlueCoast proxies
SSL Certificates: Corporate certificate management for secure connections
Internal Registries: Access to @schwab packages via internal npm registries
Authentication: GitHub token and registry authentication handling

Quality Assurance

The setup includes Git hooks that integrate with the monorepo's quality processes:

Pre-commit: Branch name validation following Schwab conventions
Pre-push: Automated execution of pnpm lint, pnpm type-check, pnpm conformance, pnpm test:fast, and pnpm build

1. Package Development

When developing shared packages:

Make changes in packages/[package-name]
Run tests: pnpm test --filter=[package-name]
Build: pnpm build --filter=[package-name]
Dependent applications automatically pick up changes

2. Application Development

When developing applications:

Start development server: pnpm dev-[app-name]
Applications automatically reload when dependencies change
Use Storybook for component development: pnpm dev-storybook

3. Cross-Package Changes

For changes affecting multiple packages:

Use Turbo's dependency graph: turbo run build
Turbo automatically builds in the correct order
Only changed packages and their dependents are rebuilt

Best Practices

Package Organization

Single Responsibility: Each package has a clear, focused purpose
Dependency Direction: Applications depend on packages, not vice versa
Interface Consistency: Shared packages expose consistent APIs

Naming Conventions

Applications: app_[domain-name] (e.g., app_www.schwab.com)
Packages: @schwab/[package-name] (e.g., @schwab/ui)
Files: Follow TypeScript and React conventions

Performance Optimization

Code Splitting: Applications use dynamic imports for large dependencies
Tree Shaking: Packages are built with tree-shaking in mind
Bundle Analysis: Regular bundle size analysis for optimization

Deployment Architecture

Vercel Integration

The monorepo is configured for Vercel deployment with:

Build Command: turbo run build
Root Directory: Application-specific deployment
Environment Variables: Managed per application
Build Caching: Turbo cache integration with Vercel

Environment Management

Each application manages its own environment configuration:

Development: .env.development
Production: Environment variables in deployment platform
Shared: Global environment variables in turbo.json

Troubleshooting

Common Issues

Build Failures: Check dependency order in turbo.json
Type Errors: Ensure @schwab/tsconfig is properly extended
Missing Dependencies: Run pnpm install in root directory
Port Conflicts: Applications use predefined ports (see table above)

Debugging Commands

# Check workspace structure
pnpm list --depth=0

# Analyze dependency graph
turbo run build --dry-run

# Clean and rebuild
pnpm clean && pnpm install && pnpm build

# Type check all packages
pnpm type-check

Repository Overview​

Key Technologies​

Directory Structure​

Applications (apps/)​

Core Web Applications​

Supporting Applications​

Content Management​

Shared Packages (packages/)​

Core Packages​

Configuration Packages​

Development Packages​

Build System Architecture​

Turbo Configuration​

Package Scripts​

Dependency Management​

Workspace Dependencies​

Version Overrides​

Development Workflow​

Container Environment Setup​

Setup Process​

Corporate Integration Features​

Quality Assurance​

1. Package Development​

2. Application Development​

3. Cross-Package Changes​

Best Practices​

Package Organization​

Naming Conventions​

Performance Optimization​

Deployment Architecture​

Vercel Integration​

Environment Management​

Troubleshooting​

Common Issues​

Debugging Commands​