Skip to main content

Quick Overview

General Overview​

Next.js Github

Refer to our main Next.js repo to use with the summary below - https://github.com/charlesschwab/nextjs-web

Next.js at Schwab is deployed with React and TypeScript using a Turborepo-based monorepo structure stored in the nextjs-web repository on GitHub Enterprise. All Next.js applications are located in the /apps directory, while all shared dependencies are in the /packages directory.

Repository Architecture​

Our monorepo follows a clear separation of concerns:

  • Applications (/apps): Ten or so Next.js applications and development tools
  • Packages (/packages): Twelve shared libraries providing reusable functionality across all applications
  • Configuration: Root-level configuration files for TypeScript, testing, linting, and build orchestration

This architecture enables:

  • Code Reusability: Shared packages eliminate duplication across applications
  • Consistent Standards: Centralized configuration ensures uniform code quality
  • Efficient Builds: Turborepo caches and parallelizes build tasks across the monorepo
  • Type Safety: Shared TypeScript configurations and type definitions across all projects

Monorepo Structure​

nextjs-web/
├── .github/                          # GitHub workflows and CI/CD configurations
│   └── copilot-instructions.md       # AI pair programming guidelines
│
├── apps/                             # All Next.js applications
│   ├── www.schwab.com/               # Public-facing website (React 19 + Next.js 15)
│   ├── client.schwab.com/            # Authenticated client portal
│   ├── nextapi.schwab.com/           # API layer and backend services
│   ├── beacon-docs/                  # Beacon design documentation
│   ├── client-central/               # Client dashboard application
│   ├── nexttools.schwab.com/         # Internal tools and utilities
│   ├── meganav-mfe/                  # Micro-frontend for navigation component
│   ├── sanity-next/                  # Headless CMS (Sanity.io)
│   ├── sanity-studio/                # Headless CMS (Sanity.io)
│   ├── storybook/                    # Design system component library (Vite-based)
│   └── docs/                         # Docusaurus documentation site (this site!)
│
├── packages/                         # Shared libraries and utilities
│   ├── ui/                           # React component library (shadcn + TailwindCSS 4)
│   ├── fetch/                        # Data fetching utilities and API clients
│   ├── transformer/                  # Data transformation and normalization
│   ├── schema/                       # Zod schemas for validation
│   ├── security/                     # Authentication, authorization, and encryption
│   ├── server-actions/               # Next.js server actions
│   ├── utilities/                    # Common helper functions
│   ├── mock-data/                    # Test fixtures and mock data
│   ├── test/                         # Shared testing utilities (Jest configuration)
│   ├── cli/                          # Command-line tools for development
│   ├── tsconfig/                     # Shared TypeScript configurations
│   └── twconfig/                     # Shared TailwindCSS configurations
│
├── biome.jsonc                       # Biome linter and formatter configuration
├── conformance.config.jsonc          # Vercel conformance rules
├── jest.config.ts                    # Root Jest testing configuration
├── turbo.json                        # Turborepo build orchestration
├── package.json                      # Root dependencies and scripts
├── pnpm-workspace.yaml               # PNPM workspace configuration
├── tsconfig.json                     # Root TypeScript configuration
└── vercel.json                       # Vercel deployment settings

Key Technologies:

  • Package Manager: pnpm 9.1+ with workspace support
  • Build System: Turborepo 2.4+ with remote caching
  • Runtime: Node.js 20.18 (Red Hat Enterprise Linux 9.5 container)
  • Framework: Next.js 15.2 with React 19
  • Styling: TailwindCSS 4.1 + CVA (Class Variance Authority)
  • Type System: TypeScript 5.8 with strict mode
  • Validation: Zod 3.24 for runtime type checking
  • Testing: Jest 29.7 with SWC transformation
  • Documentation: JSDoc 4.1 for inline code documentation

Docker Development​

Local Docker Development Only​

We are not allowing Next.js development to occur outside of Next.js Docker containers. To meet that requirement, we have created a Red Hat Linux Docker image that contains a complete development environment. We also have a docker-install.sh script that pulls the Docker Image from the Schwab Harbor repository and creates a fresh Next.js development environment.

Docker Environment Specifications:

  • Base Image: Red Hat Enterprise Linux 9.6 (Plow)
  • Node.js: Version 20.18 LTS
  • Package Manager: pnpm 9.1.1
  • Build Tools: Turborepo 2.4+, TypeScript 5.8, Jest 29.7
  • Code Quality: Biome linter/formatter, Vercel Conformance
  • Container Registry: Schwab Harbor (requires MyAccess permissions)

Benefits of Docker Development:

  • Consistency: Every developer uses identical environment and dependencies
  • Isolation: Multiple containers for parallel feature development
  • Security: Controlled environment with enterprise Linux security
  • Portability: Containers work identically on Mac, Windows, and Linux hosts

Multi-Container Workflow:

The ability to spin-up multiple Docker images, makes it very easy to work on multiple features at one time. The entire Next.js code repo is cloned to each Docker container, creating a fully isolated development environment.

Vercel Hosting​

Our Vercel site

Refer to our Vercel landing page for the information below - https://vercel.com/charles-schwab

Our Platform-as-a-Service provider for Next.js is Vercel. Every developer will have access to Vercel in order to facilitate deployment of preview builds, enablement of remote build caching, and access to performance observability dashboards, logs, and other critical release-related information.

Vercel Infrastructure:

  • Cloud Provider: AWS (Amazon Web Services)
  • Data Centers: Four (4) AWS regions across the United States
  • Edge Network: 250+ CloudFlare points of presence for edge-compute capabilities
  • Edge Compute: Budgeted capacity available (requires team approval for deployment)

Vercel Projects: Each application in our monorepo has its own Vercel project:

  • nextjs-web-www - www.schwab.com production deployments
  • nextjs-web-client - client.schwab.com production deployments
  • nextjs-web-storybook - Storybook design system
  • Additional projects for other apps in the /apps directory

Vercel deploys our application to four (4) AWS data centers across the United States, plus 250 points of presence on CloudFlare for edge-compute capabilities. There are costs associated with edge compute capabilities (we have budgeted for certain amount in our annual contract) so you will need to request guidance/approval from the team to deploy to the edge. We will scale our edge compute contract to match the needs of our developers and business partners.

Turbo Remote Build Caching​

Remote build caching is a new concept to Schwab and will enable an extraordinary boost to developer productivity. Vercel provides a cloud-based remote cache server that all our users can use to share build caches as well as with Vercel's build system.

How It Works:

  1. Local Build: When you build a Next.js app on your local machine, Turborepo generates a hash based on:

    • Source file contents
    • Dependencies
    • Environment variables
    • Build configuration

  2. Cache Upload: The build artifacts are automatically pushed to Vercel's remote cache server

  3. Cache Retrieval: When anyone (developer or CI/CD) runs the same build:

    • Turborepo checks the remote cache using the build hash
    • If a match is found, artifacts are downloaded instantly
    • No compilation needed - the build is restored from cache

Benefits:

  • Instant Builds: Download pre-built artifacts instead of recompiling
  • Team Collaboration: Share build caches across the entire development team
  • CI/CD Speed: Production deployments complete in seconds instead of minutes
  • QA Efficiency: QA can instantly pull developer builds for regression testing

Configuration: Remote caching is configured in turbo.json with task-specific cache rules. Each task defines:

  • Input files that affect the cache key
  • Output artifacts to cache (.next/**, storybook-static/**, etc.)
  • Environment variables that influence the build

This means that if you build the Next.js app on your local machine, a copy of that build will be pushed up to the remote cache server so the next person (or service) that attempts to run the same build will instantaneously download the build from cache without having to wait on the full build process to complete. QA can pull your builds immediately to review your changes for regressions, or Vercel can deploy the full application to production in a matter of seconds.

Code Contribution​

GitHub Versus BitBucket​

GitHub Enterprise is used for all code management though Bitbucket was used elsewhere at Schwab until recently. GitHub Enterprise code contribution works differently from the GitFlow method used in BitBucket.

Traditional GitFlow (BitBucket):

  • Feature branches → develop branch (dev environment)
  • develop → test branch (test environment)
  • test → master branch (production)

GitHub + Vercel Workflow:

  • Feature branches → main branch ONLY
  • No separate develop or test branches
  • Preview deployments for every branch and PR
  • Production deployments only from merged PRs to main

Branch Naming Convention:

  • Format: feature/TICKET-ID-short-description
  • Example: feature/CMS-75749-refactor-existing-docs
  • Always include the JIRA/ticket number for traceability

Test Deployments​

Vercel for GitHub will deploy every push to our nextjs-web repository by default. This includes pushes and pull requests made to feature branches. This allows those working within the repository to preview changes made before they are pushed to production.

Automatic Deployments:

  • Feature Branches: Every push creates a unique preview URL
  • Pull Requests: Dedicated preview deployment with status checks
  • Main Branch: Automatic production deployment after QA approval

Preview URLs:

  • Format: https://<app-name>-<git-branch>-charles-schwab.vercel.app
  • Shareable with team members and stakeholders
  • Includes all environment variables from Vercel project
  • Persists until branch is deleted

Quality Assurance & Deployment​

Vercel uses a full-featured Continuous Integration / Continuous Delivery model which enables us to release to production at any time without the need to wait for a scheduled release cycle. With great power comes great responsibility. In order to ensure our releases are free of deployment errors, visual defects, and performance regressions, the QA team will be the only people capable of releasing code to production.

Deployment Workflow:

  1. Developer creates pull request (PR) to main branch
  2. Vercel automatically builds a production-level preview deployment
  3. Automated checks run (TypeScript, linting, unit tests)
  4. QA team is notified for manual review
  5. QA approves and merges PR to main
  6. Automatic production deployment to Vercel

Testing Types:

  • Unit Tests: Full suite of Jest tests
  • E2E Tests: End-to-end testing using mabl
  • Visual Regression: Automated screenshot comparison (Storybook)

Vercel will build a production-level deployment for each PR and will automatically notify the QA team to conduct their final review.

The QA team is responsible for manually reviewing all PRs during a sprint, and, during the following sprint, they will create automated Unit and E2E testing scripts to ensure everything older than 2 weeks is fully auto-tested. Our target automated testing coverage is 90% for everything in production and 100% for everything older than 2 weeks.