Astroweb - Personal Website

A modern, responsive personal website built with Next.js 15, featuring a comprehensive blog, reading lists, and professional portfolio. This project demonstrates modern web development practices with static site generation, theme switching, and MDX content management.

✨ Features

🎨 Theme System

• Light, Dark, and System Themes: Automatic theme detection with window.matchMedia
• Local Storage Persistence: Remembers user preferences across sessions
• CSS Custom Properties: Dynamic color schemes that adapt to theme changes
• Hydration-Safe: Prevents flash of unstyled content during theme switching

📝 MDX Blog System

• Auto-Discovery: Automatically finds and indexes new articles
• Rich Content Support: Full MDX syntax with custom React components
• Frontmatter Management: Structured metadata for SEO and organization
• Static Generation: Pre-built pages for optimal performance

📚 Reading Lists

• Yearly Collections: Organized book lists by year (2023, 2024, 2025)
• Dynamic Data Integration: Pulls book data from JSON files at build time
• Cover Image Support: Visual representation of reading progress
• Responsive Grid Layout: Adapts to different screen sizes

🎧 Podcast Directory

• Curated Recommendations: Hand-picked podcast selections with ratings
• Category Organization: Grouped by topic and interest area
• Visual Presentation: Podcast artwork and metadata display
• Rating System: Personal ratings and notes for each podcast

🛠️ Uses Page

• Professional Tools Showcase: Development environment and tool preferences
• Technology Stack: Current tools, frameworks, and software
• Responsive Design: Mobile-first approach with Tailwind CSS
• Interactive Elements: Hover effects and smooth transitions

📱 Progressive Web App (PWA)

• Web App Manifest: site.webmanifest for app-like experience
• Multiple Favicon Sizes: Optimized for different devices and platforms
• Theme Color Configuration: Dynamic theme-aware colors
• Standalone Display Mode: Full-screen app experience

🚀 Tech Stack

Frontend Framework

• Next.js 15: Latest version with App Router architecture
• React 18: Modern React features and hooks
• TypeScript: Type-safe development with strict configuration

Styling & Design

• Tailwind CSS: Utility-first CSS framework
• Custom CSS Variables: Theme-aware color schemes
• Responsive Design: Mobile-first approach with breakpoint system
• Dark Mode Support: Comprehensive dark theme implementation

Content Management

• MDX: Markdown with JSX support
• next-mdx-remote: Server-side MDX rendering
• gray-matter: Frontmatter parsing and management
• File System API: Node.js file operations for content discovery

Build & Performance

• Static Site Generation (SSG): Pre-built pages for optimal loading
• Turbopack: Fast build tool for development
• Image Optimization: Next.js Image component with optimization
• Code Splitting: Automatic route-based code splitting

Development Tools

• ESLint: Code quality and consistency
• Prettier: Code formatting and style
• pnpm: Fast and efficient package management
• TypeScript: Static type checking and IntelliSense

Deployment & Hosting

• Firebase Hosting: Static site hosting with CDN
• GitHub Actions: Automated CI/CD pipeline
• Static Export: output: 'export' configuration
• Trailing Slashes: SEO-friendly URL structure

📁 Project Structure

src/
├── app/                    # Next.js App Router pages
│   ├── articles/          # Blog articles with MDX
│   │   ├── page.tsx      # Articles landing page
│   │   └── [slug]/       # Individual article pages
│   ├── books/            # Reading lists by year
│   │   ├── page.tsx      # Books landing page
│   │   └── [year]/       # Year-specific book pages
│   ├── projects/         # GitHub projects showcase
│   │   ├── page.tsx      # Projects landing page
│   │   └── [slug]/       # Individual project pages
│   ├── podcasts/         # Podcast recommendations
│   ├── uses/             # Professional tools showcase
│   ├── globals.css       # Global styles and CSS variables
│   ├── layout.tsx        # Root layout with navigation
│   └── page.tsx          # Home page with featured content
├── components/            # Reusable React components
│   ├── ui/               # Basic UI components
│   ├── mdx/              # MDX-specific components
│   ├── SideNavigation.tsx # Main navigation component
│   ├── ProjectCard.tsx   # Project display cards
│   ├── ArticleCard.tsx   # Article preview cards
│   └── ThemeToggle.tsx   # Theme switching component
├── content/               # MDX content files
│   ├── articles/         # Blog post MDX files
│   ├── books/            # Year-based reading list MDX files
│   └── projects/         # GitHub project MDX files
├── contexts/              # React context providers
│   └── ThemeContext.tsx  # Theme state management
├── lib/                   # Utility functions and data fetching
│   ├── articles.ts       # Article discovery and management
│   ├── books.ts          # Book data utilities
│   ├── projects.ts       # Project data utilities
│   └── utils.ts          # General utility functions
├── types/                 # TypeScript type definitions
│   ├── article.ts        # Article interface definitions
│   ├── book.ts           # Book and year interfaces
│   └── project.ts        # Project interface definitions
└── icons/                 # SVG icon components

🛠️ Getting Started

Prerequisites

• Node.js 18+: Modern JavaScript runtime
• pnpm: Fast and efficient package manager
• Git: Version control system

Installation

1. Clone the repository

   git clone https://github.com/vramdhanie/astroweb.git
   cd astroweb
   

2. Install dependencies

   pnpm install
   

3. Run the development server

   pnpm run dev
   

4. Open your browser Navigate to http://localhost:3000

Available Scripts

pnpm run dev          # Start development server with Turbopack
pnpm run build        # Build for production with static export
pnpm run build:ci     # Build for CI/CD without Turbopack
pnpm run start        # Start production server
pnpm run lint         # Run ESLint for code quality
pnpm run type-check   # Run TypeScript type checking

📝 Content Management

Adding New Articles

1. Create a new .mdx file in src/content/articles/
2. Add frontmatter with title, date, tags, and description
3. Write your content using MDX syntax
4. The article will be automatically discovered and listed

Adding New Projects

1. Create a new .mdx file in src/content/projects/
2. Add frontmatter with project metadata
3. Set highlight: true to feature on home page
4. Include GitHub URL and technology stack

Adding New Reading Years

1. Create a new .mdx file in src/content/books/
2. Add frontmatter with year, slug, cover image, and description
3. Update your books.json data file with the new year's books
4. The year will appear in the books landing page

Theme Customization

The theme system uses CSS custom properties defined in globals.css. Colors automatically adapt to light/dark modes:

:root {
  --background: #ffffff;
  --foreground: #0f172a;
  --primary: #3b82f6;
  --primary-foreground: #ffffff;
  --muted: #f1f5f9;
  --muted-foreground: #64748b;
  /* ... more variables */
}

[data-theme="dark"] {
  --background: #0f172a;
  --foreground: #f8fafc;
  --primary: #60a5fa;
  --primary-foreground: #0f172a;
  --muted: #1e293b;
  --muted-foreground: #94a3b8;
  /* ... more variables */
}

🔧 Configuration

Environment Variables

Create a .env.local file for local development:

NEXT_PUBLIC_SITE_URL=http://localhost:3000

Next.js Configuration

The project is configured for static export and optimized performance:

// next.config.ts
const nextConfig: NextConfig = {
  output: 'export',
  trailingSlash: true,
  images: {
    unoptimized: true,
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.unsplash.com',
        port: '',
        pathname: '/**',
      },
      {
        protocol: 'https',
        hostname: 's3.us-west-2.amazonaws.com',
        port: '',
        pathname: '/**',
      },
    ],
  },
}

TypeScript Configuration

Path aliases for clean imports:

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Tailwind CSS Configuration

Custom color scheme and typography:

// tailwind.config.cjs
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
  theme: {
    extend: {
      colors: {
        background: 'var(--background)',
        foreground: 'var(--foreground)',
        primary: 'var(--primary)',
        // ... more custom colors
      },
      fontFamily: {
        mono: ['var(--font-mono)', 'monospace'],
      },
    },
  },
  plugins: [],
}

🚀 Deployment

Firebase Hosting

The project is configured for Firebase Hosting with static export:

// firebase.json
{
  "hosting": {
    "public": "out",
    "ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
  }
}

GitHub Actions CI/CD

Automated deployment pipeline:

# .github/workflows/deploy-prod.yml
name: Deploy to Production
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
      - run: pnpm install
      - run: pnpm run build:ci
      - uses: FirebaseExtended/action-hosting-deploy@v0

Static Export Benefits

• Fast Loading: Pre-built HTML files
• SEO Friendly: Search engine optimized
• CDN Ready: Easy to deploy to any static hosting
• Cost Effective: No server costs for hosting

🎨 Design System

Color Palette

• Primary: Blue tones for links and accents
• Background: Light/dark theme variants
• Text: High contrast for readability
• Muted: Subtle colors for secondary elements

Typography

• Headings: Bold, monospace font for technical feel
• Body Text: Clean, readable sans-serif
• Code: Monospace font for technical content
• Hierarchy: Clear visual distinction between content levels

Layout Principles

• Mobile First: Responsive design starting from mobile
• Grid System: CSS Grid for complex layouts
• Spacing: Consistent spacing using Tailwind's scale
• Navigation: Persistent side navigation for easy access

🔍 SEO & Performance

Search Engine Optimization

• Meta Tags: Comprehensive metadata for each page
• Open Graph: Social media sharing optimization
• Structured Data: JSON-LD for rich snippets
• Sitemap: Automatic sitemap generation

Performance Optimization

• Static Generation: Pre-built pages for instant loading
• Image Optimization: Next.js Image component
• Code Splitting: Route-based code splitting
• Lazy Loading: Deferred loading of non-critical resources

Accessibility

• Semantic HTML: Proper heading hierarchy and landmarks
• Color Contrast: WCAG compliant color combinations
• Keyboard Navigation: Full keyboard accessibility
• Screen Reader Support: ARIA labels and descriptions

🤝 Contributing

Contributions are welcome! This project serves as both a personal website and a demonstration of modern web development practices.

Development Guidelines

1. Code Style: Follow ESLint and Prettier configuration
2. TypeScript: Use strict typing and avoid any
3. Component Design: Create reusable, composable components
4. Testing: Write tests for critical functionality
5. Documentation: Update README and code comments

Pull Request Process

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 Vincent Ramdhanie

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🙏 Acknowledgments

• Next.js Team: For the amazing React framework
• Tailwind CSS: For the utility-first CSS framework
• Vercel: For the deployment platform and tools
• Firebase: For hosting and infrastructure
• Open Source Community: For the tools and libraries that make this possible

📊 Project Statistics

• Lines of Code: 10,000+ (TypeScript, MDX, CSS)
• Components: 20+ reusable React components
• Pages: 25+ static pages with dynamic content
• Content: 10+ articles, 6 projects, 3 book years
• Performance: 95+ Lighthouse score
• Accessibility: WCAG 2.1 AA compliant

🎯 Future Roadmap

Short Term (Next 3 months)

• Performance Optimization: Further improve Core Web Vitals
• Content Expansion: Add more articles and projects
• Analytics Integration: User behavior tracking and insights
• Search Functionality: Full-text search across content

Medium Term (3-6 months)

• Internationalization: Multi-language support
• Advanced Theming: Custom theme builder
• Content API: Headless CMS integration
• Progressive Enhancement: Offline functionality

Long Term (6+ months)

• AI Integration: Content recommendations and search
• Community Features: Comments and discussions
• E-commerce: Digital products and services
• Mobile App: Native mobile application

---

Vincent Ramdhanie - Senior Software Engineer
🌐 Website | 💼 LinkedIn | 🐙 GitHub

About

A modern, responsive personal website built with Next.js 15, featuring a comprehensive blog, reading lists, and professional portfolio. This project demonstrates modern web development practices with static site generation, theme switching, and MDX content management.