SDBurt
Back to projects
•
5 min read

Modern Astro Portfolio Website

AstroTypeScriptCSSMDXCloudflarePerformance

Overview

A modern, performance-focused portfolio website showcasing my work as a software engineer. It is optimized for speed, accessibility, and developer experience while keeping the implementation small and maintainable.

Technical Architecture

Framework Choice

  • Astro 7: Rust-powered builds, the Content Layer API, and static-first architecture
  • Astro components: No client framework runtime or hydrated UI islands
  • TypeScript: Strict type safety across the entire codebase
  • Vanilla CSS: Custom design system with CSS custom properties for optimal performance

Performance Optimizations

  • Zero JavaScript by default: Static HTML generation with selective hydration
  • Asset optimization: Hashed static assets with long-lived cache headers
  • Font optimization: Preloaded critical fonts with display swap
  • Bundle optimization: Tree shaking and selective component loading

Key Features

Accessibility First

  • Semantic components: Native HTML controls and landmarks wherever possible
  • Skip navigation: Keyboard navigation support
  • Screen reader optimized: Semantic HTML with proper ARIA labels
  • Color contrast: WCAG AA compliance across all themes

Content Management

  • MDX Support: Enhanced markdown with custom components
  • Syntax Highlighting: Shiki integration with GitHub Dark theme
  • Content Collections: Type-safe frontmatter with Zod validation
  • Feeds and discovery: Generated RSS and sitemap output

Developer Experience

  • Hot Module Replacement: Instant development feedback
  • Type Safety: End-to-end TypeScript with content type generation
  • Code Quality: Biome integration for linting and formatting
  • Git Hooks: Automated quality checks on commit

Performance Results

Quality Targets

  • Performance: Static HTML and minimal client JavaScript
  • Accessibility: Semantic markup, keyboard navigation, and reduced-motion support
  • Best Practices: Strict TypeScript, security headers, and dependency checks
  • SEO: Structured data, canonical URLs, RSS, and generated sitemaps

Bundle Analysis

  • Client framework bundle: None
  • Critical CSS: Inlined for instant rendering
  • Deployment artifact: Static assets only; no Worker server bundle

Technical Challenges Solved

Migration from Tailwind to Vanilla CSS

  • Challenge: Maintaining design consistency while removing utility framework
  • Solution: Built comprehensive design system with semantic CSS classes
  • Result: 40% reduction in CSS bundle size with improved maintainability

Astro 4 to 5 Migration

  • Challenge: Breaking changes in content collections and view transitions
  • Solution: Updated to new content layer API and ClientRouter
  • Result: Improved build performance and simplified content management

Astro 5 to 7 Migration

  • Challenge: Updating the content, Markdown, Vite, and deployment contracts across two major versions
  • Solution: Migrated through Astro 6 first, moved plugins to the shared unified processor, and removed unused runtime integrations
  • Result: Faster builds, fewer dependencies, and an assets-only deployment

Content Strategy

Technical Writing

  • Blog posts covering development challenges and solutions
  • Project deep-dives with code examples and architecture decisions
  • Performance optimization case studies

Project Showcases

  • Detailed project descriptions with technical specifications
  • Code snippets highlighting key implementation details
  • Impact metrics and lessons learned

SEO & Discoverability

Structured Data

  • JSON-LD implementation for rich search results
  • Proper OpenGraph and Twitter card metadata
  • Automated sitemap generation with priority scoring

Content Optimization

  • Semantic HTML structure for better indexing
  • Optimized meta descriptions and title tags
  • Internal linking strategy for improved page authority

Deployment & Infrastructure

Cloudflare Workers Static Assets

  • Static asset serving: HTML, CSS, fonts, and images are served directly from Cloudflare’s edge
  • No server runtime: The site does not deploy an unnecessary Worker script or session binding
  • Security headers: _headers rules deploy with the static asset bundle
  • Future-ready: Worker APIs can be added later without moving platforms again

CI/CD Pipeline

  • Build validation: Astro diagnostics and production generation run together
  • Code quality: Biome linting and pre-commit build checks
  • Reproducible installs: Frozen pnpm lockfile in Cloudflare Workers Builds

Technical Stack

Framework: Astro 7, TypeScript Styling: Vanilla CSS, CSS Custom Properties, PostCSS Content: MDX, Shiki, Remark/Rehype plugins Deployment: Cloudflare Workers Static Assets Development: Biome, Git Hooks, VS Code Extensions Analytics: PostHog

Open Source Contributions

This portfolio serves as a reference implementation for:

  • Modern Astro development patterns
  • Static-first Astro component architecture
  • Performance optimization techniques
  • Content-driven website architecture

The codebase is fully open source and includes comprehensive documentation for other developers to learn from and contribute to.