Major Architecture Update: Astro Integration for Marketing Pages

[koistya]

We've just merged a significant architectural improvement that addresses one of the most common pain points in full-stack React applications: the awkward marriage between marketing content and application logic.

The Problem We Solved

Many of you have raised concerns about:

• Loading entire React bundles for static marketing pages
• SEO challenges with client-side rendered content pages
• Difficulty updating marketing copy without risking app functionality
• Performance overhead on pages that should be lightning fast

The Solution: Best Tool for Each Job

We've integrated Astro to handle all public-facing marketing pages while keeping React for the actual application. This isn't just a trendy tech addition - it's a fundamental improvement to how modern web applications should be architected.

What's New

Directory Structure:

apps/
├── web/                    # Marketing site (Astro)
│   ├── pages/              # Static marketing pages
│   │   ├── index.astro     # Homepage
│   │   ├── about.astro     # About page
│   │   ├── features.astro  # Features showcase
│   │   └── pricing.astro   # Pricing plans
│   └── layouts/            # Shared layouts
│
└── app/                    # Application (React)
    ├── routes/             # App routes (dashboard, settings, etc.)
    ├── components/         # App-specific components
    └── lib/                # Business logic, auth, state

Performance Improvements

The numbers speak for themselves:

• Bundle Size: 340KB → 44KB (87% reduction) for marketing pages
• Lighthouse Scores: Consistent 100s across Performance, Accessibility, Best Practices, and SEO
• Time to Interactive: Near-instant for static pages
• Build Times: Faster development with smaller, focused bundles

Developer Experience Enhancements

• Clear Separation: Marketing in apps/web, application in apps/app
• Shared Components: Both sites use @repo/ui for design consistency
• Type Safety: Full TypeScript support across both platforms
• Hot Reload: Faster refresh times during development
• Content Updates: Change marketing copy without touching app code

Migration Guide

For Existing Users:

1. Pull the latest changes
2. Run bun install to get new dependencies
3. Use bun dev:web for marketing site development
4. Use bun dev:app for application development
5. bun dev continues to run everything concurrently

No Breaking Changes: All existing URLs and routes work exactly as before. This is a transparent improvement.

Technical Implementation

Astro Configuration

• Static site generation by default
• React components supported via islands architecture
• Shared Tailwind configuration
• Optimized build output for edge deployment

Shared UI Components

// Both Astro and React import from the same source
import { Button, Card } from "@repo/ui";

Build Commands

bun build        # Build everything
bun build:web    # Build marketing site only
bun build:app    # Build application only

Why This Matters

This change represents our commitment to:

1. Performance First: Using the right tool for each job
2. Developer Productivity: Clear boundaries and faster iteration
3. Maintainability: Separation of concerns at the architecture level
4. Future Proof: Ready for CMS integration, i18n, A/B testing

What's Next?

This foundation opens up several exciting possibilities:

• Progressive enhancement with selective hydration
• Edge-side includes for personalized content
• CMS integration for marketing team autonomy
• International content delivery

Get Involved

• Try it out: Pull the latest and experience the improvements
• Report issues: Open an issue if you encounter any problems
• Contribute: PRs welcome for further optimizations
• Share feedback: Let us know how this works for your use case

Resources

• Pull Request #2098
• Astro Documentation
• Migration Checklist

---

This is the kind of architectural decision that seems obvious in hindsight but takes courage to implement. Thanks to everyone who provided feedback that led to this improvement. Your production apps just got significantly faster.