/marcusrbrown.github.io

Primary LanguageTypeScript

mrbro.dev

Build Status Open in GitHub Codespaces Node version TypeScript License: MIT

Testing Status

Unit Tests E2E Tests Visual Regression Accessibility Performance Bundle Size CI/CD Test Health

Coverage Details

  • Statements: Statements
  • Branches: Branches
  • Functions: Functions
  • Lines: Lines

Test Suite Status

  • Unit Tests: Comprehensive test coverage with Vitest
  • E2E Tests: Cross-browser testing with Playwright (Chromium, Firefox, WebKit)
  • Visual Regression: Automated screenshot comparisons across themes
  • Accessibility: WCAG 2.1 AA compliance testing with axe-core
  • Performance: Lighthouse CI monitoring with Core Web Vitals
  • Bundle Analysis: JavaScript bundle size tracking and optimization

⭐ If you like this project, star it on GitHub — it helps a lot!

Features • Getting Started • Technology Stack • Architecture • Testing • Deployment

A modern, high-performance developer portfolio built with React 19+, TypeScript, and Vite. Features an advanced theme system, GitHub API integration, and automated deployment to GitHub Pages with the custom domain mrbro.dev.

[!NOTE] Modern Architecture: This project uses pure ESM modules, React 19+, and cutting-edge tooling for optimal performance and developer experience.

Features

  • 🎨 Advanced Theme System - Custom theme creator with 10+ preset themes (Material, Dracula, Nord, Solarized), import/export functionality, and JSON schema validation
  • 📱 GitHub Integration - Dynamic repository showcase and blog system powered by GitHub Issues API
  • 💻 Syntax Highlighting - Theme-aware code blocks with Shiki supporting 15+ programming languages
  • ⚡ Performance Optimized - Bundle analysis, code splitting, modern ES2020+ target, and automated performance monitoring
  • 🚀 Modern Stack - React 19, TypeScript strict mode, Vite 7+, React Router v7+, and pnpm package management
  • 📊 Comprehensive Testing - 80%+ test coverage with Vitest, happy-dom, and automated CI/CD pipeline
  • 🎯 Developer Experience - Git hooks with lint-staged, ESLint 9+ flat config, and Prettier integration
  • 📈 Build Analytics - Automated bundle size analysis with GitHub Actions job summaries

Getting Started

There are multiple ways to get started with this project.

The quickest way is to use GitHub Codespaces that provides a preconfigured environment for you. Alternatively, you can set up your local environment following the instructions below.

GitHub Codespaces

You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code:

Open in GitHub Codespaces

VSCode Dev Container

A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the Dev Containers extension.

You will also need to have Docker installed on your machine to run the container.

Local Environment

You need to install following tools to work on your local machine:

Then you can get the project code:

  1. Clone the repository:

    git clone https://github.com/marcusrbrown/marcusrbrown.github.io.git

  2. Navigate to the project directory:

    cd marcusrbrown.github.io

  3. Install dependencies:

    pnpm install

  4. Run the development server:

    pnpm dev

  5. Open your browser and visit http://localhost:5173 to see the portfolio in action.

Technology Stack

Core Technologies

  • React 19+ - Latest React with concurrent features and modern hooks
  • TypeScript - Strict type checking with modern ES2020+ target
  • Vite 7+ - Lightning-fast build tool with HMR and optimized production builds
  • React Router v7+ - Modern client-side routing with data loading
  • pnpm - Fast, disk space efficient package manager

Theme System

  • Custom Theme Engine - Advanced theming with CSS custom properties
  • Preset Collection - 10+ professionally designed themes
  • Schema Validation - JSON schema validation with Ajv for theme import/export
  • WCAG Compliance - All themes meet WCAG 2.1 AA contrast requirements

Development Tools

  • ESLint 9+ - Modern flat config with comprehensive rules
  • Prettier - Code formatting with 120-proof config
  • Vitest - Fast unit testing with happy-dom environment
  • Simple Git Hooks - Automated code quality enforcement
  • Shiki - Advanced syntax highlighting with theme integration

Build & Deployment

  • GitHub Actions - Comprehensive CI/CD with matrix testing
  • GitHub Pages - Static hosting with custom domain support
  • Bundle Analysis - Automated performance monitoring and alerts
  • Cross-Platform Testing - Ubuntu, Windows, macOS compatibility

Architecture

Theme System Architecture

The project implements a comprehensive theme system using Context + Hook pattern:

// Advanced theme management with custom creation, presets, and persistence
const { currentTheme, themeMode, toggleTheme, setCustomTheme } = useTheme()

Key Features:

  • Custom Theme Creator - Full HSL color controls with real-time preview
  • Preset Gallery - Curated collection including GitHub, Material, Nord, Solarized themes
  • Import/Export - JSON-based theme sharing with validation
  • Performance Optimized - CSS custom property updates with reduced motion support

GitHub API Integration

Direct fetch API implementation for dynamic content:

// Repository showcase and blog system
const repositories = await fetchRepositories('marcusrbrown')
const blogPosts = await fetchBlogPosts('marcusrbrown/marcusrbrown.github.io')

Features:

  • Repository Display - Automatic showcase of GitHub projects
  • Blog System - GitHub Issues with 'blog' label converted to blog posts
  • No External Dependencies - Pure fetch API implementation

Code Quality Architecture

  • Git Hooks Integration - Automatic ESLint fixes and formatting on commit
  • Comprehensive Testing - 80%+ coverage with component and integration tests
  • Performance Monitoring - Bundle size tracking with automated warnings
  • Cross-Platform CI - Matrix testing across multiple operating systems

Testing

This project implements a comprehensive testing strategy ensuring code quality, functionality, and performance across all aspects of the application.

Test Coverage Requirements

  • Minimum Coverage: 80% across statements, branches, functions, and lines
  • Current Coverage: See badges above for real-time metrics
  • Coverage Reports: Generated automatically in CI and available in ./coverage/

Unit Testing with Vitest

pnpm test              # Run all unit tests
pnpm test --coverage   # Generate coverage report
pnpm test --watch      # Run tests in watch mode
pnpm test --ui         # Open Vitest UI in browser

Features:

  • Fast Execution: Vitest's native ESM support and multithreading
  • Component Testing: React Testing Library integration
  • Happy DOM: Lightweight DOM environment for browser API testing
  • Coverage: V8 coverage provider with HTML reports

End-to-End Testing with Playwright

pnpm test:e2e                    # Run E2E tests (all browsers)
pnpm test:e2e:headed            # Run with visible browser
pnpm test:e2e:ui                # Open Playwright UI
pnpm test:accessibility         # Run accessibility tests
pnpm test:visual                # Run visual regression tests

Multi-Browser Support:

  • Chromium: Primary testing browser
  • Firefox: Cross-browser compatibility
  • WebKit: Safari engine testing

Test Types:

  • Functional: User workflows and interactions
  • Visual Regression: Screenshot comparisons across themes
  • Accessibility: WCAG 2.1 AA compliance validation
  • Performance: Core Web Vitals monitoring

Performance Testing

pnpm test:performance           # Run Lighthouse CI
pnpm test:performance:budgets   # Validate performance budgets
pnpm test:performance:dashboard # Generate performance reports

Monitoring:

  • Lighthouse CI: Automated performance scoring
  • Bundle Analysis: JavaScript size tracking
  • Core Web Vitals: LCP, FID, CLS measurements
  • Performance Budgets: Automated alerts for regressions

Test Dashboard

The project includes a comprehensive test dashboard that aggregates results from all test suites:

pnpm dashboard         # Generate dashboard data
pnpm badges           # Update README badges

Dashboard Features:

  • Health Score: Weighted score across all test types
  • Historical Trends: Track performance over time
  • Badge Generation: Automated status badges for README
  • CI Integration: Automatic updates on every build

Running Tests Locally

  1. Install dependencies:

    pnpm install

  2. Run full test suite:

    pnpm test:all

  3. Generate reports:

    pnpm dashboard && pnpm badges

CI/CD Testing Pipeline

The GitHub Actions workflow includes:

  • Unit Tests: Run on every PR and push
  • E2E Tests: Cross-browser matrix testing
  • Visual Tests: Automated screenshot comparison
  • Accessibility: Compliance validation
  • Performance: Budget enforcement
  • Coverage: Automated badge updates

Deployment

GitHub Pages Setup

The site is automatically deployed to GitHub Pages using GitHub Actions:

  • Custom Domain: mrbro.dev
  • Automatic Deployment: Triggered on push to main branch
  • Build Analysis: Comprehensive bundle size reporting
  • Performance Monitoring: Automated warnings for bundle size thresholds

Environment Configuration

  • GITHUB_PAGES=true - Automatically set by GitHub Actions
  • Custom domain configured via CNAME file
  • SHA-pinned actions for security

Development

Available Scripts

pnpm install        # Install dependencies with frozen lockfile
pnpm dev           # Start development server with HMR
pnpm build         # Build for production with type checking
pnpm preview       # Preview production build locally
pnpm test          # Run test suite with coverage
pnpm lint          # Lint codebase with ESLint
pnpm fix           # Auto-fix linting issues
pnpm setup-hooks   # Manually setup git hooks

Code Quality

The project enforces high code quality standards:

  • Automatic Git Hooks - ESLint fixes and Prettier formatting on commit
  • Strict TypeScript - No any types, comprehensive type checking
  • Test Coverage - Minimum 80% coverage requirement
  • Modern Standards - ESM-only, React 19 patterns, performance best practices

Performance Guidelines

  • JavaScript bundles should stay under 500KB (warnings generated above this)
  • Total bundle size should stay under 2MB maximum
  • Build analysis automatically tracks and reports size metrics
  • Performance optimizations include code splitting and modern ES2020+ target

Resources

Here are some resources to learn more about the technologies used:

Troubleshooting

Common Issues

  1. Node.js Version - Ensure you're using Node.js v22+ LTS
  2. Package Manager - This project requires pnpm, not npm or yarn
  3. Git Hooks - Run pnpm run setup-hooks if pre-commit hooks aren't working
  4. Build Errors - Check that all dependencies are installed with pnpm install --frozen-lockfile

Debug Commands

pnpm install --frozen-lockfile  # Exact dependency install
pnpm build --debug             # Verbose build output
pnpm test --reporter=verbose    # Detailed test output
pnpm run setup-hooks           # Reinstall git hooks

[!TIP] Performance: The build analysis script provides detailed bundle metrics and optimization suggestions in GitHub Actions job summaries.