Installation

This guide will help you install and set up Express Base API on your local machine.

Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Description
Node.js	>= 18.x	JavaScript runtime
npm	>= 9.x	Package manager
MongoDB	>= 5.0	Database (or MongoDB Atlas)
Redis	>= 6.x	Queue and caching (optional but recommended)
TypeScript	>= 5.x	Type checking

Verify Prerequisites

# Check Node.js version
node --version
# Should output: v18.x.x or higher

# Check npm version
npm --version
# Should output: 9.x.x or higher

# Check MongoDB
mongod --version
# Should output: db version v5.x.x or higher

# Check Redis (optional)
redis-server --version
# Should output: Redis server v=6.x.x or higher

Installation Steps

1. Clone the Repository

git clone https://github.com/mrnjifanda/jifijs.git
cd express-backend-ts

2. Install Dependencies

npm install

This will install all required dependencies including:

• Express.js
• TypeScript
• Mongoose (MongoDB ODM)
• Redis client (ioredis)
• JWT authentication
• And many more...

3. Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env with your configuration:

# Application
PORT=3000
NODE_ENV=development
APP_NAME="Express Base API"
APP_URL=http://localhost:3000
FRONTEND_URL=http://localhost:5173

# Database
MONGODB_URI=mongodb://localhost:27017/express-base
MONGODB_USER=
MONGODB_PASSWORD=

# Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_REFRESH_SECRET=your-refresh-secret-key-change-this-too
JWT_EXPIRES=24h
JWT_REFRESH_EXPIRES=7d
OTP_EXPIRES=10m

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_URL=redis://localhost:6379

# Email (SMTP)
SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525
SMTP_SECURE=false
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SMTP_FROM=noreply@example.com
SMTP_FROM_NAME="Express Base API"

# Features
USE_DATABASE=yes
USE_QUEUE=yes
USE_MAIL=yes

Important

Always change the default JWT secrets in production! The example values are not secure.

4. Start Services

Start MongoDB

If using local MongoDB:

# On Ubuntu/Debian
sudo systemctl start mongod

# On macOS with Homebrew
brew services start mongodb-community

# Or run manually
mongod --dbpath /path/to/data/db

Start Redis (Optional but Recommended)

If using local Redis:

# On Ubuntu/Debian
sudo systemctl start redis-server

# On macOS with Homebrew
brew services start redis

# Or run manually
redis-server

tip

Redis is optional but highly recommended for caching and queue features. If Redis is unavailable, the application will use in-memory fallbacks.

5. Run the Application

Development Mode (with hot reload)

npm run dev

Production Build

npm run build
npm start

6. Verify Installation

Open your browser and navigate to:

• API: http://localhost:3000
• API Documentation: http://localhost:3000/api-docs

You should see:

{
  "status_code": 200,
  "status": "SUCCESS",
  "message": "Welcome to Express Base API",
  "data": {
    "is_production": false,
    "port": "3000",
    "name": "Express Base API",
    "version": "1.0.7"
  }
}

Optional Setup

Email Testing with MailDev

For development, use MailDev to test emails locally:

npm run start:maildev

Then access MailDev UI at http://localhost:1080 to see all sent emails.

Database Seeding

Create initial admin user and test data:

# Run seeders
npm run seed

# Or manually create admin user
node utils/seeders/run.js

This creates an admin user with credentials from your .env file:

• Email: USER_EMAIL from .env
• Password: USER_PASSWORD from .env

Docker Installation (Alternative)

If you prefer using Docker:

# Start services with Docker Compose
docker-compose up -d

# Stop services
docker-compose down

The docker-compose.yml includes:

• MongoDB
• Redis
• The Express application

Troubleshooting

MongoDB Connection Error

❌ Database connection failed: connect ECONNREFUSED 127.0.0.1:27017

Solution: Ensure MongoDB is running:

sudo systemctl status mongod
# or
mongod --dbpath /path/to/data/db

Redis Connection Error

⚠️ Redis connection failed

Solution: Check if Redis is running:

redis-cli ping
# Should respond: PONG

Or disable Redis in .env:

USE_QUEUE=no

Port Already in Use

Error: listen EADDRINUSE: address already in use :::3000

Solution: Change the PORT in .env or kill the process using port 3000:

# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

Next Steps

Now that you have Express Base API installed:

1. Quick Start Guide - Build your first API endpoint
2. Architecture Overview - Understand the structure
3. Code Generator - Generate resources quickly

---

Need help? Check our GitHub Issues or contact support@njifanda.com