Meganav MFE Application

The Meganav MFE (Micro Front-End) is a specialized Next.js application that provides navigation components and functionality across multiple Charles Schwab web properties. It serves as a modular, reusable navigation system that can be embedded into other applications.

Overview

• Application: apps/meganav-mfe
• Port: 3011
• Version: 1.0.60
• Framework: Next.js 15.3.2 with React 19.1.0
• Purpose: Micro front-end for navigation components and shared UI elements

Key Features

• Micro Front-End Architecture: Designed for embedding in other applications
• Shared Navigation Components: Provides consistent navigation across Schwab properties
• React-to-HTML Conversion: Specialized endpoints for rendering React components as HTML
• Feature Flag Integration: Built-in feature flag support for dynamic behavior
• Adobe React Spectrum Integration: Utilizes Adobe's design system components
• Performance Optimized: Built with Next.js caching and optimization features

Technical Architecture

Framework Stack

Technology	Version	Purpose
Next.js	15.3.2	React framework with SSR/SSG
React	19.1.0	Component library
TypeScript	5.8.2	Type safety and development experience
Sass	1.86.1	CSS preprocessing
Tailwind CSS	4.1.11	Utility-first styling

Core Dependencies

Key dependencies from package.json

{
  "@schwab/beacon-design-tokens": "^1.24.29",
  "@schwab/fetch": "workspace:*",
  "@schwab/schema": "workspace:*",
  "@schwab/twconfig": "workspace:*",
  "@schwab/ui": "workspace:*",
  "@schwab/utilities": "workspace:*",
  "@schwab/security": "workspace:*",
  "react-aria": "^3.38.1",
  "botid": "^1.5.3"
}

Monorepo Integration

The application leverages several internal packages:

• @schwab/ui: Shared React component library
• @schwab/fetch: HTTP client utilities
• @schwab/schema: Data validation schemas
• @schwab/security: Security utilities and middleware
• @schwab/twconfig: Tailwind CSS configuration
• @schwab/beacon-design-tokens: Design system tokens

Directory Structure

apps/meganav-mfe/
├── src/
│   ├── app/                    # App Router directory (Next.js 13+)
│   │   └── api/               # API routes
│   ├── pages/                 # Pages Router (legacy/specific routes)
│   │   ├── api/               # API endpoints
│   │   ├── react2html/        # React-to-HTML conversion endpoints
│   │   └── global.css         # Global styles
│   ├── flags/                 # Feature flag configuration
│   │   ├── flags/             # Individual flag definitions
│   │   └── index.ts           # Flag exports
│   ├── global/                # Global styles and utilities
│   │   ├── icons.scss         # Icon definitions
│   │   ├── styles.scss        # Global SCSS styles
│   │   └── windowDataLayer.tsx # Analytics data layer
│   └── instrumentation-client.ts # Client-side instrumentation
├── public/                    # Static assets
│   ├── fonts/                 # Font files
│   ├── nextassets/            # Next.js specific assets
│   ├── shell/                 # Shell-related assets
│   └── ira-poc/               # IRA proof-of-concept assets
├── .allowlists/               # Security allowlist configurations
├── next.config.js             # Next.js configuration
├── postcss.config.js          # PostCSS configuration
└── tsconfig.json              # TypeScript configuration

Development Workflow

Local Development

Development commands

# Install dependencies
pnpm install

# Start development server on port 3011
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Type checking
pnpm type-check

# Conformance checking
pnpm conformance

The development server automatically runs on port 3011 with process management to prevent port conflicts.

Build Configuration

The application uses several key configurations:

Next.js Configuration

• Experimental Features: Enabled caching for performance
• React Strict Mode: Enabled for development safety
• Trailing Slash: Required for consistent URLs
• Transpiled Packages: Adobe React Spectrum components

TypeScript Integration

• Strict Mode: Enabled for type safety
• Shared Configuration: Extends @schwab/tsconfig
• Type Checking: Integrated into build process

API Architecture

React-to-HTML Conversion

The application provides specialized endpoints for converting React components to HTML:

/pages/react2html/[sitename]/

This functionality enables:

• Server-side rendering of navigation components
• Integration with non-React applications
• Static HTML generation for performance

API Routes

• Pages Revalidation: /api/pages-revalidate.ts - Handles on-demand revalidation
• Dynamic Routes: Support for site-specific navigation rendering

Feature Flag System

The application includes a comprehensive feature flag system:

Feature flag structure

// src/flags/index.ts
export * from './flags/';

// Individual flag files in src/flags/flags/

This enables:

• A/B Testing: Dynamic feature rollouts
• Progressive Enhancement: Gradual feature releases
• Environment-Specific Behavior: Different configs per environment

Security and Performance

Security Measures

• Allowlist Configuration: Defined security boundaries
• BotId Integration: Bot detection and management
• Edge Config: Vercel Edge Config for dynamic configuration
• CSRF Protection: Built-in Next.js security features

Performance Optimizations

• Next.js 15 Features: Latest performance improvements
• Caching Strategy: Experimental caching enabled
• Font Optimization: Automatic font loading optimization
• Bundle Optimization: Transpiled packages for better bundling

Integration Patterns

Micro Front-End Usage

The application is designed for embedding in other applications:

1. iFrame Integration: Can be embedded as iframe
2. Component Federation: Shared component export
3. API Integration: HTML rendering endpoints
4. Asset Sharing: Static asset serving

Cross-Application Communication

Testing Strategy

Development Testing

• Jest Integration: Testing framework setup
• React Testing Library: Component testing
• Mock Data: @schwab/mock-data integration
• JSDOM: Browser environment simulation

Quality Assurance

• Type Checking: TypeScript strict mode
• Linting: Integrated code quality checks
• Conformance: Vercel conformance rules
• Build Validation: Production build verification

Deployment and Operations

Build Process

1. Dependency Installation: pnpm workspace resolution
2. Type Generation: TypeScript compilation
3. Asset Optimization: Next.js build optimization
4. Static Generation: Pre-rendered pages and assets

Monitoring and Debugging

• Client-Side Instrumentation: Built-in performance monitoring
• Data Layer Integration: Analytics tracking
• Error Boundaries: React error handling
• Development Tools: Next.js developer experience

Common Use Cases

Navigation Integration

Example navigation usage

// Embedding navigation component
import { Navigation } from '@schwab/ui';

export default function Layout() {
  return (
    <div>
      <Navigation site="www.schwab.com" />
      <main>{/* Page content */}</main>
    </div>
  );
}

HTML Endpoint Usage

Fetching rendered navigation HTML

# Get navigation HTML for specific site
curl https://meganav-mfe.vercel.app/react2html/www.schwab.com/

# Integration with non-React applications
fetch('/api/navigation-html')
  .then(response => response.text())
  .then(html => {
    document.getElementById('navigation').innerHTML = html;
  });

Troubleshooting

Common Issues

Issue	Cause	Solution
Port 3011 in use	Previous process not killed	Run kill script in dev command
Build failures	Type errors	Run pnpm type-check
Missing styles	CSS not loading	Check PostCSS configuration
Component not rendering	Import path issues	Verify workspace dependencies

Development Tips

Performance

Enable React DevTools Profiler when debugging performance issues in navigation components.

Security

Always validate navigation data through Zod schemas before rendering to prevent XSS attacks.

Future Enhancements

• Module Federation: Enhanced micro front-end capabilities
• Edge Runtime: Improved performance with edge computing
• Component Library: Expanded shared component exports
• Analytics Integration: Enhanced tracking and monitoring

This micro front-end architecture enables Charles Schwab to maintain consistent navigation experiences across multiple applications while providing flexibility for individual product teams.