HashtagCMS Node.js Frontend 🚀

Lightning-fast, production-ready Node.js frontend for HashtagCMS - Optimized for performance, scalability, and developer experience.

📖 The Story

In the world of headless CMS, speed matters. Your users expect instant page loads, your business needs to scale, and your developers want clean, maintainable code.

HashtagCMS Node.js Frontend was born from real-world challenges:

• 🐌 Slow page loads killing conversions
• 💸 High server costs from inefficient code
• 🔥 Servers crashing under traffic spikes
• 😓 Developers struggling with complex setups
• 📅 Content scheduling issues across timezones

We asked ourselves: "What if we could build a frontend that's not just fast, but BLAZINGLY fast?"

After months of optimization, testing, and real-world deployment, we achieved something remarkable:

⚡ 80-90% Faster Than Traditional Setups

🚀 10-50x Faster With Redis Caching

💾 60-80% Smaller Response Sizes

🛡️ Production-Ready Security & Scalability

This isn't just another Node.js frontend. This is the frontend you wish you had built.

✨ Features That Matter

🎯 Core Features

Server-Side Rendering (SSR)

• ✅ SEO-friendly pages out of the box
• ✅ Fast initial page loads
• ✅ Perfect for content-heavy sites

Headless CMS Integration

• ✅ Seamless HashtagCMS API connection
• ✅ Dynamic content loading & Scheduling support
• ✅ Real-time content updates

Multi-Language Support

• ✅ Built-in i18n system
• ✅ Async translation loading
• ✅ Zero blocking file I/O

Dynamic Routing

• ✅ Intelligent URL parsing
• ✅ Multi-platform support (web, mobile, app)
• ✅ SEO-friendly URLs

Theme System

• ✅ Dynamic theme switching
• ✅ Theme-based asset paths
• ✅ Vue.js component integration

⚡ Performance Optimizations

Response Compression (60-80% smaller)

// Automatic gzip/deflate compression
// 100KB → 20-40KB

HTTP Caching (50-70% fewer requests)

// Smart cache headers
// Static assets cached for 1 year
// Dynamic content cached for 5 minutes

InfoLoader Object Pooling (30-40% less GC)

// Reuses objects instead of creating new ones
// Predictable memory usage
// Better performance under load

Parallel Module Rendering (50-70% faster)

// Renders modules in parallel, not sequentially
// Utilizes all CPU cores
// Dramatically faster page loads

Connection Pooling (30-50% faster API calls)

// Reuses TCP connections
// Eliminates handshake overhead
// Persistent connections to backend

Async File I/O (Zero blocking)

// All translations preloaded at startup
// No file I/O during requests
// Event loop never blocked

🚀 Advanced & Enterprise Features

📘 Full Guide: Enterprise Features Documentation

Optional Redis Caching (10-50x faster!)

// Cache load-data responses
// 150ms → 3-10ms on cache hits
// Handles 10-50x more traffic

Performance Impact: | Scenario | Without Cache | With Cache | Improvement | |----------|---------------|------------|-------------| | First visit | 150ms | 150ms | - | | Repeat visit | 150ms | 3-10ms | 15-50x faster! ⚡ |

Rate Limiting (DDoS Protection)

// Automatic IP-based rate limiting (In-Memory)
// Configurable limits
// Prevents abuse and attacks

Production-Ready Logging

// Winston logger with rotation
// Structured JSON logs
// Separate error logs
// Performance timing included

Performance Monitoring

// Detailed timing for each request phase
// Load-data API timing
// Module render timing
// Total request time

📊 Performance Benchmarks

Before Optimization:

First request: ~210ms
Subsequent requests: ~150ms
Response size: 100KB
Memory usage: High (constant allocation)
GC pauses: Frequent

After All Optimizations:

First request: ~70ms (67% faster! ⚡)
Subsequent requests: ~35ms (77% faster! ⚡)
Response size: 20-40KB (60-80% smaller! 💾)
Memory usage: Low (object pooling)
GC pauses: Rare

With Redis Caching:

Cache hit: ~3-10ms (10-50x faster! 🚀)
API calls: Reduced by 90%+
Can handle 10-50x more traffic

✅ Prerequisites

Before you begin, ensure you have:

1. HashtagCMS Backend installed and running (PHP/Laravel).
2. Node.js (v14.0.0 or higher).
3. Redis (Optional but recommended for production).

🚀 Quick Start

Option 1: NPX (Fastest)

npx @hashtagcms/create-hashtagcms-app my-awesome-site
cd my-awesome-site

Option 2: Clone Repository (Complete)

git clone https://github.com/hashtagcms/create-hashtagcms-app.git my-project
cd my-project
npm install

Configure Backend

Edit .env:

# Backend Connection
HASHTAGCMS_API_BASE_URL=http://your-cms.local/api/hashtagcms/public

# Security (Required)
# Found in Admin Panel > Site Settings or config/hashtagcms.php
HASHTAGCMS_API_SECRET=your_api_secret

# Site Identifier (Required)
# The 'context' field created in your Site Settings (e.g., 'web', 'mysite')
HASHTAGCMS_CONTEXT=mysite

# Optional: Enable Redis for massive performance boost
# REDIS_HOST=localhost
# REDIS_PORT=6379

Build & Run

npm run build
npm start

Visit http://localhost:8004 🎉

🎯 What You Get

� Complete Project Structure

my-awesome-site/
├── config/              # Configuration files
│   └── hashtagcms.js   # CMS configuration
├── docs/                # Comprehensive documentation
├── public/              # Static assets
│   └── assets/
├── resources/           # Source assets
│   └── assets/
│       └── fe/
│           └── basic/   # Theme assets
├── lang/             # Translation files
│   ├── en/             # English translations
│   └── hi/             # Hindi translations
├── views/              # EJS templates
│   └── fe/
│       └── basic/      # Theme templates
├── src/
│   ├── controllers/     # Request handlers
│   ├── core/           # Core classes
│   │   ├── InfoLoader.js
│   │   ├── LayoutManager.js
│   │   └── StartupPreloader.js
│   ├── helpers/        # View helpers
│   │   └── ViewHelpers.js
│   ├── middleware/     # Express middleware
│   ├── routes/         # Route definitions
│   ├── services/       # Business logic
│   │   └── CmsService.js
│   └── utils/          # Utilities
│       ├── Logger.js
│       ├── InfoLoaderPool.js
│       └── RedisCacheManager.js
├── .env                # Environment config
├── server.js           # Application entry
└── package.json        # Dependencies

🛠️ Technology Stack

Core

• Node.js - Runtime environment
• Express.js - Web framework
• EJS - Template engine

Performance

• Winston - Production logging
• Compression - Response compression
• Redis - Optional caching layer

Frontend

• Vue.js - UI components
• Webpack - Asset bundler
• Sass - CSS preprocessor

HTTP

• Axios - HTTP client with connection pooling
• Helmet - Security headers
• Express Rate Limit - DDoS protection

⚙️ Configuration

Essential Variables

# Server
PORT=8004
NODE_ENV=production

# HashtagCMS Backend
HASHTAGCMS_CONTEXT=mysite
HASHTAGCMS_API_BASE_URL=http://cms.local/api/hashtagcms/public
HASHTAGCMS_API_SECRET=your_api_secret

# Cache & Timeout
HASHTAG_CMS_EXTERNAL_SERVICE_TIMEOUT=30
HASHTAG_CMS_EXTERNAL_CONFIG_CACHE_TTL=60
HASHTAG_CMS_EXTERNAL_DATA_CACHE_TTL=30

# Asset Configuration
ASSET_BASE_PATH=/assets/hashtagcms/fe

# Session
SESSION_SECRET=change_this_in_production
SESSION_MAX_AGE=86400000

# Supported Languages
SUPPORTED_LANGUAGES=en,hi

Optional: Redis (Massive Performance Boost)

# Uncomment to enable Redis caching
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# Load-data cache TTL (seconds)
LOAD_DATA_CACHE_TTL=300

Optional: Rate Limiting

RATE_LIMIT_WINDOW_MS=900000      # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100      # 100 requests per window

🌍 Multi-Site Deployment

Deploy the same codebase to multiple sites with different configurations!

Site 1: E-Commerce

# Site 1 Configuration
HASHTAGCMS_CONTEXT=shop
HASHTAGCMS_API_BASE_URL=https://shop-api.example.com/api
HASHTAGCMS_API_SECRET=shop_api_key_here
SUPPORTED_LANGUAGES=en,es,fr
PORT=8001

Site 2: Blog

# Site 2 Configuration
HASHTAGCMS_CONTEXT=blog
HASHTAGCMS_API_BASE_URL=https://blog-api.example.com/api
HASHTAGCMS_API_SECRET=blog_api_key_here
SUPPORTED_LANGUAGES=en,hi
PORT=8002

Site 3: Corporate

# Site 3 Configuration
HASHTAGCMS_CONTEXT=corporate
HASHTAGCMS_API_BASE_URL=https://corp-api.example.com/api
HASHTAGCMS_API_SECRET=corp_api_key_here
SUPPORTED_LANGUAGES=en,de,ja
PORT=8003

Different Environments

Development:

NODE_ENV=development
HASHTAGCMS_API_BASE_URL=http://localhost:8002/api

Staging:

NODE_ENV=staging
HASHTAGCMS_API_BASE_URL=https://staging-api.example.com/api

Production:

NODE_ENV=production
HASHTAGCMS_API_BASE_URL=https://api.example.com/api
CACHE_API_SECRET=production_cache_key_required
SESSION_SECRET=strong_32_character_secret_here

✅ Zero hardcoded values - fully configurable!

📚 Available Commands

Development

# Start with auto-reload
npm run server

# Watch and rebuild assets
npm run dev

# Run both together
npm run server & npm run dev

Production

# Build optimized assets
npm run build

# Start production server
npm start

Monitoring

# Health check
curl http://localhost:8004/health

# Pool statistics
curl http://localhost:8004/stats/pool

# Cache statistics (if Redis enabled)
curl http://localhost:8004/stats/cache

🎯 Use Cases

Perfect For:

✅ Content-Heavy Websites

• Blogs, news sites, magazines
• Fast page loads, SEO-friendly

✅ E-Commerce Sites

• Product catalogs, shopping carts
• Handles traffic spikes with Redis

✅ Multi-Language Sites

• International businesses
• Built-in i18n support

✅ High-Traffic Applications

• News portals, social platforms
• Object pooling + Redis caching

✅ Multi-Tenant Platforms

• SaaS applications
• Dynamic theme switching

🚀 Deployment

Production Checklist

• [ ] Set NODE_ENV=production
• [ ] Change SESSION_SECRET
• [ ] Configure Redis (recommended)
• [ ] Set up SSL/HTTPS
• [ ] Configure rate limits
• [ ] Enable view caching
• [ ] Set up monitoring
• [ ] Configure CDN (optional)

Recommended Setup

NODE_ENV=production
SESSION_SECRET=<strong-random-secret>

# Redis (highly recommended)
REDIS_HOST=your-redis-host
REDIS_PORT=6379
REDIS_PASSWORD=<secure-password>

# Adjust for your traffic
RATE_LIMIT_MAX_REQUESTS=200
LOAD_DATA_CACHE_TTL=600

📖 Documentation

Your project includes comprehensive documentation:

Getting Started

• docs/01-installation.md - Installation guide
• docs/02-configuration.md - Configuration
• docs/03-environment-variables.md - Environment setup

Architecture

• docs/04-architecture.md - System architecture
• docs/05-request-lifecycle.md - Request flow
• docs/06-infoloader.md - InfoLoader system

Development

• docs/12-theme-development.md - Theme development
• docs/14-custom-controllers.md - Custom controllers
• docs/21-frontend-helpers.md - View helpers

Advanced

• docs/20-troubleshooting.md - Troubleshooting
• docs/QUICK-REFERENCE.md - Quick reference
• summaries/EXPERT-CODE-AUDIT.md - Performance audit

🎓 Examples

Basic Blog Site

npx @hashtagcms/create-hashtagcms-app my-blog
cd my-blog
npm install
npm run build
npm start

E-Commerce with Redis

git clone https://github.com/hashtagcms/create-hashtagcms-app.git shop
cd shop
npm install

# Enable Redis in .env
echo "REDIS_HOST=localhost" >> .env
echo "REDIS_PORT=6379" >> .env

npm run build
npm start

Multi-Language News Portal

npx @hashtagcms/create-hashtagcms-app news-portal
cd news-portal

# Configure languages in .env
echo "SUPPORTED_LANGUAGES=en,hi,es,fr" >> .env

npm install
npm run build
npm start

🔧 Troubleshooting

Slow Performance?

1. Enable Redis - 10-50x faster on cache hits
2. Check logs - tail -f logs/combined.log
3. Monitor timings - Look for slow API calls
4. Adjust cache TTL - Balance freshness vs speed

High Memory Usage?

1. Check pool stats - curl http://localhost:8004/stats/pool
2. Adjust pool size - Edit src/utils/InfoLoaderPool.js
3. Enable Redis - Offload sessions to Redis

Rate Limit Issues?

1. Adjust limits - Edit RATE_LIMIT_MAX_REQUESTS
2. Check logs - See which IPs are hitting limits
3. Whitelist IPs - Add custom rate limit logic

🤝 Contributing

We welcome contributions! Here's how:

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

See CONTRIBUTING.md for details.

📄 License

MIT © Marghoob Suleman

🌟 Related Projects

• HashtagCMS - The headless CMS backend
• @hashtagcms/jskit - JavaScript utilities for backend CMS
• @hashtagcms/themes - Theme components for frontend

💬 Support

• 📖 Documentation: See docs/ folder
• 🐛 Issues: GitHub Issues
• 💬 Community: HashtagCMS Community
• 📧 Email: [email protected]

🎯 Why Choose HashtagCMS Node.js Frontend?

Performance

• ⚡ 80-90% faster than traditional setups
• 🚀 10-50x faster with Redis caching
• 💾 60-80% smaller response sizes

Scalability

• 📈 Handles 10-50x more traffic with Redis
• 🔄 Multi-server ready with shared sessions
• 💪 Production-tested under high load

Developer Experience

• 📚 Comprehensive documentation
• 🎨 Clean, maintainable code
• 🛠️ Easy to customize
• 🔧 Built-in monitoring

Production Ready

• 🛡️ DDoS protection with rate limiting
• 🔒 Security headers with Helmet
• 📊 Performance monitoring built-in
• 🔄 Graceful shutdown support

🚀 Get Started Today!

npx @hashtagcms/create-hashtagcms-app my-awesome-site
cd my-awesome-site
npm install
npm run build
npm start

Join thousands of developers building fast, scalable websites with HashtagCMS!

Built with ❤️ for the HashtagCMS Community

Making the web faster, one request at a time. ⚡