Installation Guide
This guide will help you install and configure the Blog Marketing Platform for local development or production deployment.System Requirements
Before you begin, ensure your system meets these requirements:- Node.js: Version 18.0 or higher
- Package Manager: npm, pnpm, or yarn
- Git: For cloning the repository
- Modern Browser: Chrome, Firefox, Safari, or Edge
- Operating System: macOS, Linux, or Windows
Recommended: Use pnpm for faster installations and better disk space efficiency.
Installation Methods
Choose the installation method that best fits your needs:- Local Development
- Production Deployment
- Docker
Perfect for development, testing, and contributing to the project.
Local Development Setup
Follow these steps to set up the platform for local development:Install Dependencies
Install all required dependencies using your preferred package manager:This will install all dependencies from
package.json, including:- Astro 5.13.3
- React 19.1.1
- Zustand 5.0.8
- Tailwind CSS 4.1.12
- And all other required packages
Configure Environment Variables
Create your environment configuration file:Then edit
.env.local with your configuration:.env.local
Environment Variables Reference
Environment Variables Reference
| Variable | Description | Default |
|---|---|---|
VITE_API_BASE_URL | Backend API base URL | http://localhost:3000/api/v1 |
Start Development Server
Launch the development server:The server will start at
http://localhost:4321You should see output like:Configuration Options
API Mode Configuration
The platform supports two modes: Mock Mode (default) and Real API Mode.Mock Mode is perfect for:
- Frontend development without backend dependency
- UI/UX testing and demos
- Learning the platform
- Backend API running (see Backend Setup below)
- Valid
VITE_API_BASE_URLin.env.local
Astro Configuration
The platform uses Astro with these integrations:astro.config.mjs
Configuration Options Explained
Configuration Options Explained
- site: Your production URL (used for sitemap generation)
- integrations: React for components, sitemap for SEO
- output:
staticfor SSG,serverfor SSR - adapter: Deployment adapter (Vercel, Netlify, etc.)
Backend Setup
To use the platform with a real backend API:Backend Requirements
The platform expects a RESTful API with these endpoints:
POST /auths/sign-in- User loginPOST /auths/sign-up- User registrationPOST /auths/sign-out- User logoutPOST /auths/refresh- Token refreshGET /posts- List postsPOST /posts- Create postGET /categorias- List categoriesGET /comentarios- List comments- And more… (see API documentation)
Start Backend Server
Follow your backend’s installation instructions to start the API server.Example for Node.js backend:Ensure it’s running on the port specified in
VITE_API_BASE_URL (default: 3000)Build for Production
When you’re ready to deploy to production:Build the Project
Create an optimized production build:This generates static files in the
dist/ directory.Preview Production Build
Test the production build locally:This serves the
dist/ folder at http://localhost:4321Project Structure
Understand the key directories and files:Development Workflow
Authentication Flow
The platform uses JWT-based authentication:State Management with Zustand
The platform uses Zustand for global state management:Troubleshooting
Port Already in Use
Port Already in Use
If port 4321 is already in use:Or update
astro.config.mjs:API Connection Errors
API Connection Errors
If you’re getting API connection errors:
- Check
VITE_API_BASE_URLin.env.local - Verify backend is running:
curl http://localhost:3000/api/v1/health - Check CORS configuration in backend
- Look for errors in browser console
- Try switching to mock mode:
USE_REAL_API: false
Build Errors
Build Errors
If you encounter build errors:
Module Not Found Errors
Module Not Found Errors
If you see “Cannot find module” errors:
Available Scripts
Common commands for development and deployment:| Command | Description |
|---|---|
npm run dev | Start development server at localhost:4321 |
npm run build | Build production bundle to ./dist/ |
npm run preview | Preview production build locally |
npm run astro | Run Astro CLI commands |
astro check | Check for TypeScript and Astro errors |
astro add | Add integrations (e.g., astro add react) |
Next Steps
Now that you have the platform installed:Quickstart Guide
Create your first blog post and explore features.
API Configuration
Connect to your backend and configure endpoints.
Customize Theme
Customize colors, fonts, and branding.
Deploy
Deploy to production with Vercel or Netlify.
Additional Resources
- Astro Documentation: Learn more about Astro
- React Documentation: React best practices
- Zustand Guide: State management patterns
- Tailwind CSS: Utility-first CSS framework
Installation complete! You’re ready to start building with Blog Marketing Platform.