Skip to main content

​
Project Overview

The Blog Marketing Platform is a modern, full-featured content management and marketing platform built with Astro, React, and TypeScript. The architecture follows a hybrid approach, leveraging Astro’s static site generation capabilities while using React for interactive components.

​
Tech Stack

Frontend Framework

Astro 5.13.3 - Multi-page application with static generation

UI Library

React 19 - Interactive components and state management

Type Safety

TypeScript - Full type safety across the application

Styling

Tailwind CSS 4 - Utility-first CSS framework

​
Core Dependencies

{
  "astro": "^5.13.3",
  "@astrojs/react": "^4.3.1",
  "@astrojs/mdx": "^4.3.5",
  "@astrojs/sitemap": "^3.6.0",
  "@astrojs/vercel": "^9.0.0"
}

​
Project Structure

/
├── public/                  # Static assets
│   ├── images/
│   └── favicon.svg
├── src/
│   ├── assets/             # Project assets
│   ├── components/         # React components
│   │   ├── admin/          # Admin dashboard components
│   │   ├── animations/     # Animation components
│   │   ├── auth/           # Authentication UI
│   │   ├── blog/           # Blog-related components
│   │   ├── comments/       # Comment system
│   │   ├── dashboard/      # Dashboard widgets
│   │   ├── editor/         # MDX editor components
│   │   ├── home/           # Homepage sections
│   │   ├── layout/         # Layout components
│   │   ├── profile/        # User profile components
│   │   ├── tools/          # Marketing tools (ROI calc, etc.)
│   │   └── ui/             # Reusable UI components
│   ├── config/             # Configuration files
│   │   └── api.ts          # API configuration
│   ├── contexts/           # React contexts
│   ├── data/               # Mock data & constants
│   ├── hooks/              # Custom React hooks
│   ├── layouts/            # Astro layouts
│   │   └── Layout.astro    # Main layout
│   ├── lib/                # Utility libraries
│   │   └── apiClient.ts    # HTTP client
│   ├── pages/              # Astro pages (file-based routing)
│   │   ├── admin/          # Admin routes
│   │   ├── auth/           # Auth pages
│   │   ├── blog/           # Blog pages
│   │   └── index.astro     # Homepage
│   ├── schemas/            # Zod validation schemas
│   ├── services/           # API service layer
│   ├── styles/             # Global styles
│   │   └── tailwind.css
│   ├── types/              # TypeScript type definitions
│   └── utils/              # Utility functions
├── astro.config.mjs        # Astro configuration
├── tailwind.config.js      # Tailwind configuration
└── tsconfig.json           # TypeScript configuration

​
Key Directories Explained

All React components are organized by feature:
  • admin/ - Admin dashboard UI (posts, users, analytics)
  • ui/ - Reusable components (Button, Input, Modal, Card)
  • layout/ - Header, Footer, navigation
  • editor/ - MDX editor for creating posts
  • profile/ - User profile and settings forms
Astro uses file-based routing:
  • index.astro → /
  • blog/index.astro → /blog
  • blog/[slug].astro → /blog/:slug (dynamic)
  • admin/posts/index.astro → /admin/posts
Each .astro file can contain frontmatter, components, and HTML.
Service modules handle all backend communication:
  • authService.ts - Authentication (login, register)
  • postsService.ts - Posts CRUD and advanced queries
  • usersService.ts - User management
  • commentsService.ts - Comments system
  • rbacService.ts - Roles and permissions
Each service supports both mock data and real API.
  • api.ts - API endpoints, base URL, mock/real API toggle
  • Environment variables via .env.local

​
Architecture Patterns

​
1. Hybrid Rendering

---
// Static page with SSG
import Layout from '../layouts/Layout.astro';
import Header from '../components/layout/Header.tsx';

const posts = await fetch('/api/posts').then(r => r.json());
---

<Layout title="Blog">
  <Header client:load />
  <!-- Static content generated at build time -->
</Layout>

​
2. Client Directives

Astro components are static by default. Use client directives for interactivity: 
<Header client:load />        <!-- Load immediately -->
<Modal client:idle />         <!-- Load when browser idle -->
<Chart client:visible />      <!-- Load when visible -->
<Widget client:only="react" /> <!-- Only render on client -->

​
3. Service Layer Pattern

All API calls go through service modules with mock/real API switching: 
// src/services/postsService.ts
import { useRealApi } from '../config/api';
import { apiClient } from '../lib/apiClient';

export async function getAllPosts() {
  if (!useRealApi()) {
    return mockPosts; // Development mode
  }
  
  return apiClient.get('/posts'); // Production
}

​
Build Configuration

astro.config.mjs
export default defineConfig({
  site: 'https://marketing-digital-pro.com',
  integrations: [react(), sitemap()],
  output: 'static', // Static site generation
  adapter: vercel(),
  vite: {
    plugins: [tailwindcss()],
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            'react-vendor': ['react', 'react-dom'],
            'charts': ['recharts'],
            'motion': ['framer-motion']
          }
        }
      }
    }
  }
});

​
Performance Optimizations

Code Splitting

Automatic code splitting by route and manual chunks for large dependencies

Image Optimization

Lazy loading and responsive images with proper sizing

CSS Optimization

Purged unused CSS, critical CSS inlining

Bundle Analysis

Vendor chunks separated (React, charts, icons, motion)
The application uses static site generation (SSG) by default for optimal performance. Dynamic features are handled client-side with React.

​
Environment Configuration

Create a .env.local file in the project root:
.env.local
VITE_API_BASE_URL=http://localhost:3000/api/v1
Environment variables must be prefixed with VITE_ to be accessible in the browser.

​
Development Workflow

1

Install Dependencies

npm install
2

Start Dev Server

npm run dev
Runs on http://localhost:4321
3

Build for Production

npm run build
Outputs to ./dist/
4

Preview Production Build

npm run preview

​
Next Steps

Services Layer

Learn about the API service architecture

Components

Explore the component structure

State Management

Understand Zustand stores and state

API Reference

View the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us