Personal Website & Portfolio Platform

Built a modern, performant, and fully internationalized personal website using Next.js 15 App Router, featuring a unified MDX content system, dynamic SEO optimization, GDPR-compliant cookie consent, and comprehensive E2E testing with Playwright.

Overview

This personal website and portfolio platform represents a comprehensive full-stack project showcasing modern web development best practices. Built with Next.js 15 App Router, React 19, and TypeScript, the platform serves as both a professional portfolio and a technical blog, demonstrating expertise in frontend architecture, internationalization, SEO optimization, and quality assurance.

The project features a unified content management system using MDX, full bilingual support (English/Spanish), dynamic SEO infrastructure, GDPR-compliant cookie consent, and comprehensive end-to-end testing. Every architectural decision was made with scalability, maintainability, and performance in mind.

Challenges

The project faced several critical challenges:

• Unified Content Management: Creating a single content system that handles both static pages (services, about) and dynamic blog posts with consistent formatting and component reuse
• Full Internationalization: Implementing seamless bilingual support (English/Spanish) with proper SEO hreflang tags, URL routing, and content localization
• SEO Optimization at Scale: Generating dynamic sitemaps with proper internationalization links, OG image generation, and metadata management for all content types
• GDPR Compliance: Building a cookie consent system that integrates with analytics while respecting user privacy preferences
• Developer Experience: Creating reusable MDX components that work seamlessly in both page and article contexts
• Content Organization: Managing blog posts across multiple categories with proper frontmatter parsing and file system reading
• Performance Optimization: Implementing intelligent caching strategies and optimizing static asset delivery
• Quality Assurance: Establishing comprehensive E2E testing infrastructure with visual regression testing

Solution

I implemented a comprehensive solution addressing all these challenges:

Next.js 15 App Router Architecture: Leveraged the latest Next.js App Router with React Server Components to build a performant, SEO-friendly application. The architecture separates concerns with route groups (site) and (landing), enabling different layouts for different sections while maintaining code organization.

Unified MDX Content System: Designed and implemented a revolutionary unified content management system where both static pages and blog posts use the same MDX format with custom components. The CustomMDX component intelligently switches between "page" and "article" layouts, applying appropriate styling and component behavior based on context. This eliminates content duplication and ensures consistency across the entire site.

Dynamic Content Reading Utilities: Created sophisticated file system reading utilities (readContent.ts and readPost.ts) that recursively scan directories, parse frontmatter, and organize content by language and category. The system automatically handles nested categories, missing files, and provides fallback content, making content management effortless.

Full Internationalization with next-intl: Implemented comprehensive i18n support using next-intl with middleware-based locale detection and routing. The system supports seamless language switching, preserves URL structure, and includes proper SEO hreflang tags in the sitemap. All content, including blog posts, services, and static pages, is fully localized.

Dynamic Sitemap Generation with hreflang: Built an intelligent sitemap generator (app/sitemap.xml/route.ts) that automatically discovers all routes (static pages, services, and blog posts), generates proper XML with hreflang alternates for each language, and includes last-modified dates. The system ensures proper SEO indexing for both languages without manual maintenance.

GDPR-Compliant Cookie Consent System: Developed a sophisticated cookie consent system that uses dual storage (cookies for server-side access and localStorage for client-side analytics integration). The system dispatches custom events when consent changes, allowing Google Analytics to react dynamically. Users can accept all, reject all, or customize preferences, with all choices persisted across sessions.

Technology Mapping Utility: Created a centralized technology mapping system (techMapping.ts) that normalizes technology names, maps them to icons and colors, and provides consistent display across the portfolio. This eliminates inconsistencies and makes adding new technologies trivial.

Custom MDX Component Library: Built a comprehensive library of reusable MDX components including <Quote>, <Highlight>, <IconCard>, <ProjectImages>, <LeftBannerService>, and more. These components work seamlessly in both page and article contexts, providing rich content authoring capabilities while maintaining design consistency.

Middleware-Based Performance Optimization: Implemented intelligent caching in middleware (middleware.ts) that sets aggressive cache headers for static assets (1 year) while allowing dynamic content to be fresh. The middleware also adds custom headers for debugging and request tracking.

Comprehensive E2E Testing Infrastructure: Established a robust Playwright testing setup with visual regression testing, multi-locale testing, and comprehensive coverage of critical user flows. Tests include cookie consent interactions, language switching, form submissions, and page rendering validation across desktop and mobile viewports.

Server Actions for Contact Form: Implemented a contact form using Next.js Server Actions with Mailgun integration for reliable email delivery. The form includes reCAPTCHA integration for spam protection and proper error handling with user feedback.

OG Image Generation: Created dynamic OG image generation (app/og/route.tsx) using Next.js ImageResponse API, enabling social media sharing with custom preview images for all pages.

Reading Time Calculation: Implemented Medium-style reading time calculation for blog posts, automatically computing reading time based on word count (200 words per minute) to improve user experience.

Platform Screenshots

Ingenious Ideas

Several architectural decisions demonstrate innovative problem-solving:

Unified MDX Content System: The most ingenious aspect is the unified content system where the same MDX format and components work for both static pages and blog posts. The CustomMDX component uses a layout prop to switch contexts, applying different styles and behaviors. This eliminates the need for separate content systems and ensures design consistency. The system automatically handles code highlighting with sugar-high, custom table components, and intelligent link handling that preserves locale in URLs.

Dual-Storage Cookie Consent: The cookie consent system ingeniously uses both cookies (for server-side access) and localStorage (for client-side analytics scripts) with event dispatching. When consent changes, a custom event is dispatched, allowing Google Analytics to react without page reload. This provides seamless integration while maintaining GDPR compliance.

Dynamic Sitemap with Content Discovery: The sitemap generator automatically discovers all content by reading the file system, parsing frontmatter, and generating proper hreflang alternates. It handles both static routes (defined in constants) and dynamic routes (blog posts), creating a unified sitemap without manual maintenance. The system groups routes by path (without locale) and generates alternates for each language.

Technology Mapping Normalization: The technology mapping utility handles various naming conventions (e.g., "Next.js", "nextjs", "next") and normalizes them to a single icon and color. This prevents inconsistencies when different team members or content sources use different names for the same technology.

Content Reading with Fallbacks: The content reading utilities gracefully handle missing files, invalid frontmatter, and provide sensible defaults. This makes the system resilient to content errors and ensures the site never breaks due to malformed content files.

Middleware-Based Caching Strategy: Instead of configuring caching in multiple places, the middleware centralizes cache control logic. It intelligently identifies static assets by URL patterns and applies aggressive caching, while dynamic routes remain fresh. This approach simplifies cache management and improves performance.

Visual Regression Testing: The Playwright setup includes screenshot comparison testing, enabling visual regression detection. This catches unintended UI changes that might not be caught by functional tests, ensuring design consistency across updates.

Technical Architecture

Frontend Stack:

• Next.js 15.2.4 with App Router
• React 19.1.0 with Server Components
• TypeScript 5.3.3 for type safety
• Tailwind CSS 4.1.3 for styling
• Framer Motion for animations

Internationalization:

• next-intl 3.26.5 for i18n
• Middleware-based locale detection
• Dynamic routing with locale preservation

Content Management:

• next-mdx-remote 5.0.0 for MDX rendering
• sugar-high 0.6.0 for syntax highlighting
• Custom MDX component library

Testing:

• Playwright 1.51.0 for E2E testing
• Visual regression testing
• Multi-locale test coverage

Infrastructure:

• Vercel for deployment
• Mailgun for email delivery
• Google Analytics with consent management

Results

The project achieved significant success:

• Full Bilingual Support: Successfully implemented seamless English/Spanish support with proper SEO hreflang tags, enabling the site to serve both markets effectively
• Unified Content System: Created a single MDX-based content system that handles both pages and blog posts, reducing maintenance overhead and ensuring consistency
• Dynamic SEO Infrastructure: Implemented automatic sitemap generation with hreflang alternates, improving SEO scores and ensuring proper indexing for both languages
• GDPR Compliance: Built a comprehensive cookie consent system that respects user privacy while enabling analytics integration
• Comprehensive Testing: Established robust E2E testing infrastructure with visual regression testing, ensuring quality and preventing regressions
• Performance Optimization: Achieved excellent performance scores through intelligent caching, server-side rendering, and optimized asset delivery
• Developer Experience: Created reusable components and utilities that make content authoring and site maintenance effortless
• Scalable Architecture: Built a foundation that can easily accommodate new content types, languages, and features without architectural changes

Key Metrics

• Languages Supported: 2 (English, Spanish)
• Content Types: Pages, Services, Blog Posts, Projects
• Blog Categories: 4+ (React, Node.js, Python, Engineering)
• E2E Test Coverage: Critical user flows across both locales
• Performance: Excellent Lighthouse scores across all metrics
• SEO: Proper hreflang implementation for international SEO