Skip to main content

The packages Directory

This page explains every package in /home/nextjs-web/packages and how they're actually used across the monorepo applications.

Package Overview​

The packages directory contains 13 shared packages that provide reusable functionality across all applications in the monorepo:

/home/nextjs-web/packages/
├── cli/              # Schwab CLI development tools
├── fetch/            # Centralized API client library
├── mock-data/        # Test data and fixtures
├── processors/       # Data processing utilities
├── schema/           # Zod schemas for type validation
├── security/         # Security utilities and CSP
├── server-actions/   # Next.js server actions
├── test/             # Testing utilities and helpers
├── transformer/      # Content transformation tools
├── tsconfig/         # TypeScript configurations
├── twconfig/         # Tailwind CSS configurations
├── ui/               # Shared React component library
└── utilities/        # Common utility functions

Development Tools​

cli/ - Schwab CLI Tools​

Package name: @schwab/cli Type: CommonJS module Private: No (can be published)

Purpose: Custom command-line interface for development workflow automation.

Key scripts:

  • checkout.mjs - Automated branch creation with Jira integration
  • commit.mjs - Standardized commit process
  • pullflags.mjs - Feature flag management
  • ready.mjs - PR preparation and validation
  • pr.mjs - Pull request management
  • worklog.mjs - Time tracking integration

Dependencies:

  • Inquirer for interactive prompts
  • Octokit for GitHub API integration
  • Chalk for colored terminal output

Used by: Developers via terminal commands (schwab checkout, schwab commit, etc.)

test/ - Testing Infrastructure​

Package name: @schwab/test Purpose: Shared testing utilities, mocks, and configurations.

Contents:

  • Jest configurations
  • Test utilities and helpers
  • Mock implementations for external services
  • Shared test data

Used by: All applications and packages for unit/integration testing

Data & API Packages​

fetch/ - Centralized API Client​

Package name: @schwab/fetch
Type: ES Module Private: Yes Size: Large (132 dependencies in package.json)

Purpose: Centralized library for all external API calls and data fetching.

Key features:

  • Path mapping: Uses # imports for clean module resolution
  • Service integrations: Drupal, Bynder, CXP, RRBUS, SFMC
  • Specialized clients: Edge config, feature toggles, React to HTML

Directory structure:

src/
├── bynder/          # Bynder DAM API client  
├── client-fetch/    # Client-side fetch utilities
├── csim/           # CSIM service integration
├── cxp/            # Customer Experience Platform
├── drupal/         # Drupal CMS API client
├── edge-config-db/ # Edge configuration database
├── feature-toggle/ # Feature flag API client
├── react2html/     # Server-side rendering utilities
├── rrbus/          # RRBUS content service
├── sfmc/           # Salesforce Marketing Cloud
├── utilities/      # Fetch utility functions
└── vercel/         # Vercel platform integration

Used by: All applications for external API communication

schema/ - Type Validation​

Package name: @schwab/schema Type: ES Module Private: Yes

Purpose: Zod schemas for runtime type validation and TypeScript type generation.

Organization:

  • #schemas/ui/* - UI component schemas
  • #schemas/enums/* - Enumeration definitions
  • #schemas/factories/* - Schema factory functions
  • #schemas/fetched/* - API response schemas
  • #schemas/processed/* - Processed data schemas
  • #schemas/transformed/* - Transformed content schemas

Used by: All applications for type-safe data validation

mock-data/ - Test Fixtures​

Purpose: Standardized test data and mock objects.

Contents:

  • API response mocks
  • Component test fixtures
  • User personas for testing
  • Sample content data

Used by: Testing suites across all applications

UI & Styling Packages​

ui/ - Component Library​

Package name: @schwab/ui Type: ES Module
Private: No Size: Massive (310 dependencies in package.json)

Purpose: Shared React component library with standardized UI components.

Key features:

  • Path-mapped imports: Each component has a dedicated import path
  • Component categories: Accordion, Button, Card, Form inputs, Layout, Navigation
  • Utility components: Background images, loaders, capture utilities
  • Styling integration: Built-in Tailwind CSS integration

Directory structure:

src/
├── Loaders/        # Loading state components
├── Ups/           # User experience components
├── components/    # Main component library (50+ components)
├── fetch-test/    # Component testing utilities
├── jsonld/        # JSON-LD schema components
├── styles/        # Global styling utilities
└── utilities/     # Component helper functions

Sample components:

  • Accordion, AccordionItem
  • Button, ButtonGroup
  • Card, ArticleTile
  • Command, Collection
  • Form inputs and controls
  • Navigation elements

Used by: All applications for consistent UI components

twconfig/ - Tailwind Configuration​

Purpose: Standardized Tailwind CSS configurations.

Contents:

  • Base Tailwind config
  • Schwab brand theme variables
  • Custom utility classes
  • Design system tokens

Used by: Applications using Tailwind CSS for styling

Configuration Packages​

tsconfig/ - TypeScript Configuration​

Purpose: Shared TypeScript configurations for consistent compilation settings.

Contents:

  • Base tsconfig.json templates
  • App-specific TypeScript configurations
  • Strict typing rules
  • Module resolution settings

Used by: All TypeScript applications and packages

security/ - Security Utilities​

Package name: @schwab/security Type: ES Module Private: Yes

Purpose: Security-related utilities and configurations.

Key features:

  • Content Security Policy (CSP) management
  • LaunchDarkly feature flag security
  • Authentication helpers
  • Security header utilities

Main export: ContentSecurityPolicy for CSP header management

Used by: All applications for security compliance

Processing & Transformation​

processors/ - Data Processing​

Purpose: Data processing and transformation utilities.

Contents:

  • Content processors for CMS data
  • Data normalization functions
  • Format converters
  • Validation pipelines

Used by: Applications processing external data (CMS content, API responses)

transformer/ - Content Transformation​

Purpose: Content transformation tools for CMS and external data.

Contents:

  • Drupal content transformers
  • Rich text processors
  • Media asset transformers
  • Content structure normalizers

Used by: Applications consuming CMS content

server-actions/ - Server Actions​

Purpose: Next.js server actions for server-side functionality.

Contents:

  • Form submission handlers
  • Database operations
  • API integrations
  • Background job triggers

Used by: Next.js applications using App Router server actions

Utility Packages​

utilities/ - Common Functions​

Package name: @schwab/utilities Type: ES Module Private: Yes

Purpose: Shared utility functions used across the monorepo.

Directory structure:

src/
├── flags/         # Feature flag utilities
├── functions/     # General utility functions
├── logger/        # Logging utilities
└── sfmc/         # Salesforce Marketing Cloud utilities

Features:

  • Feature flag management
  • Logging infrastructure
  • Common data manipulation functions
  • SFMC integration utilities

Testing: Includes comprehensive Jest test suite

Used by: All applications and other packages for common functionality

Package Architecture Patterns​

Import Path Mapping​

Many packages use path mapping with # syntax for clean imports:

// Instead of relative paths
import { Button } from '../../../components/Button/Button'

// Use mapped paths
import { Button } from '#components/Button'

Workspace Dependencies​

Packages reference each other using workspace:*:

{
  "dependencies": {
    "@schwab/utilities": "workspace:*"
  }
}

Module Types​

  • ES Modules: Modern packages (fetch, ui, utilities)
  • CommonJS: Legacy compatibility (cli)
  • Mixed: Some packages support both

Privacy Settings​

  • Private packages: Cannot be published to npm
  • Public packages: Can be published if needed

Package Dependencies​

High-level dependency flow:​

applications → ui → utilities
applications → fetch → utilities, security
applications → schema → utilities
applications → server-actions → fetch, schema

Core dependencies:​

  • Most packages depend on @schwab/utilities
  • UI components may depend on @schwab/schema
  • API clients depend on @schwab/security

Development Workflow​

Working with packages:​

# Build all packages
cd /home/nextjs-web
pnpm build

# Work on specific package
cd packages/ui
pnpm dev

# Test a package
cd packages/utilities
pnpm test

# Type check
pnpm type-check

Adding new functionality:​

  1. Choose the right package based on functionality
  2. Follow existing patterns for imports and exports
  3. Update package.json if adding dependencies
  4. Add tests for new functionality
  5. Update documentation as needed

This package architecture enables code reuse, maintains consistency, and provides a clear separation of concerns across the entire monorepo.