newsletter

Newsletter Subscription Web Application

A full-stack newsletter and subscription management system built with React and Node.js. image

Features

Tech Stack

Frontend

Backend

Project Structure

newsletter/
├── package.json             # Root package.json with dev scripts
├── package-lock.json        # Root dependency lock file
├── backend/                 # Node.js API server
│   ├── package.json        # Backend dependencies
│   ├── package-lock.json   # Backend dependency lock file
│   ├── config/             # Database configuration
│   ├── middleware/         # Auth and admin middleware
│   ├── models/            # Database models (MongoDB/PostgreSQL)
│   ├── routes/            # API routes
│   └── server.js          # Express server entry point
├── frontend/              # React web application
│   ├── package.json      # Frontend dependencies (includes optional markdown packages)
│   ├── package-lock.json # Frontend dependency lock file
│   ├── public/           # Static assets
│   └── src/
│       ├── components/   # Reusable React components
│       ├── pages/        # Page components (Admin.js contains editor)
│       ├── hooks/        # Custom React hooks
│       ├── utils/        # Utilities and API functions
│       └── styles/       # CSS and styling
└── shared/               # Shared utilities

Key Dependencies by Directory:

Important Files for CI/CD:

Getting Started

Prerequisites

Installation

  1. Clone the repository 
    git clone <repository-url>
cd newsletter
  2. Install dependencies 
    # Install root dependencies (creates package-lock.json)
npm install

# Install backend dependencies (creates backend/package-lock.json)
cd backend
npm install

# Install frontend dependencies (creates frontend/package-lock.json)
cd ../frontend
npm install

# For markdown support (optional - if you want markdown editing capabilities)
# These packages enable dual Rich Text / Markdown editor modes
cd ../frontend
npm install marked react-markdown remark-gfm rehype-raw rehype-sanitize
npm install sanitize-html

    Package Notes:

    • marked - Fast markdown parser and compiler
    • react-markdown - React component for rendering markdown
    • remark-gfm - GitHub Flavored Markdown support (tables, task lists, etc.)
    • rehype-raw - Allows raw HTML in markdown
    • rehype-sanitize - Sanitizes HTML for security

    Workflow Best Practices:

    • Commit all package-lock.json files to version control
    • Use npm ci in production/CI environments for faster, reliable installs
    • Never manually edit package-lock.json files

  3. Environment Setup

    Create a .env file in the backend directory:

    PORT=5050
NODE_ENV=development
CLIENT_URL=http://localhost:3030
   
# Database Configuration
# Choose: 'mongodb' or 'postgresql'
DATABASE_TYPE=mongodb
   
# MongoDB Configuration (if using MongoDB)
MONGODB_URI=mongodb://localhost:27017/newsletter
   
# PostgreSQL Configuration (if using PostgreSQL)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=newsletter
POSTGRES_USER=newsletter_user
POSTGRES_PASSWORD=newsletter_password
   
JWT_SECRET=your-super-secret-jwt-key
   
# Email configuration (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
FROM_EMAIL=your-email@gmail.com

# hCaptcha configuration
HCAPTCHA_SECRET=your-hcaptcha-secret-key

  4. Database Setup

    The application supports both MongoDB and PostgreSQL. Choose your preferred database:

    For MongoDB:

    • Set DATABASE_TYPE=mongodb in your .env file
    • Install MongoDB locally or use MongoDB Atlas (cloud)

    For PostgreSQL:

    • Set DATABASE_TYPE=postgresql in your .env file
    • Install PostgreSQL locally or use a cloud service

    See MONGODB_SETUP.md for detailed database installation instructions.

  5. Start the Application

    From the root directory:

    # Start both frontend and backend concurrently
npm run dev
   
# Or start them separately:
# Backend (from backend directory)
npm run dev
   
# Frontend (from frontend directory)  
npm start
  6. Access the Application
    • Frontend: http://localhost:3030
    • Backend API: http://localhost:5050

API Endpoints

Public Endpoints

Admin Endpoints (Require Authentication)

Usage

For Visitors

  1. Visit the homepage to browse newsletters
  2. Click on any newsletter to read the full content
  3. Use the subscribe page to join the mailing list
  4. Manage subscription status (subscribe/unsubscribe)

For Admins

  1. Access the admin panel at /admin
  2. Login with admin credentials
  3. Manage newsletters (create, edit, delete, publish)
    • Rich Text Mode: Use the WYSIWYG editor with formatting toolbar
    • Markdown Mode: Write content in Markdown for faster, cleaner editing
    • Preview: Real-time preview of your newsletter content
  4. View subscriber statistics
  5. Send newsletters to subscribers

Content Creation Features

Development

Available Scripts

Root directory:

Backend directory:

Frontend directory:

Environment Variables

Backend environment variables (.env):

CI/CD Workflow

Package Lock Files: Each directory contains a package-lock.json file that locks exact dependency versions:

Production Deployment:

# Use npm ci for faster, reliable installs in production
npm ci                    # Install root dependencies
cd backend && npm ci      # Install backend dependencies  
cd ../frontend && npm ci  # Install frontend dependencies
npm run build            # Build frontend for production

Docker Considerations:

Security Features

Troubleshooting

Common Installation Issues

Package Lock File Conflicts If you encounter dependency conflicts or inconsistent installs:

# Clean install from lock files (recommended)
npm ci

# Or if you need to regenerate lock files:
rm -rf node_modules package-lock.json
npm install

# For specific directories:
cd backend
rm -rf node_modules package-lock.json
npm install

cd ../frontend  
rm -rf node_modules package-lock.json
npm install

Markdown Dependencies (Optional) If you encounter issues with markdown packages:

# Clear npm cache and reinstall
npm cache clean --force
cd frontend
rm -rf node_modules package-lock.json
npm install
npm install marked react-markdown remark-gfm rehype-raw rehype-sanitize

Node Version Compatibility

Database Connection Issues

Port Conflicts If ports 3030 or 5050 are in use:

SMTP Email Issues

hCaptcha Issues

Contributing

Development Workflow

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Important: Commit package-lock.json files if dependencies changed
  5. Test your changes locally
  6. Submit a pull request

Version Control Best Practices

Always Commit These Files:

Never Commit These Files:

Dependency Management:

License

This project is licensed under the MIT License.

Support

For support or questions, please open an issue in the repository.

Anti-Spam Protection: OpenCaptcha

This project uses OpenCaptcha to prevent spam subscriptions.

Installation

Frontend & Backend:

cd frontend
C:\Users\marood\Documents\workspace\node-v22.18.0-win-x64\npm.cmd install axios

cd ../backend
C:\Users\marood\Documents\workspace\node-v22.18.0-win-x64\npm.cmd install axios

Usage

Documentation

Enable/Disable CAPTCHA (Frontend)

To control whether CAPTCHA is shown on the subscription form, set the following in frontend/.env:

REACT_APP_ENABLE_CAPTCHA=true   # Show CAPTCHA (recommended)
REACT_APP_ENABLE_CAPTCHA=false  # Hide CAPTCHA (not recommended for production)

The backend always requires CAPTCHA verification for subscriptions. The frontend controls whether the CAPTCHA widget is displayed to users.

This site is open source. Improve this page.