Aller au contenu principal

Installation

This guide will help you install and set up JifiJs on your local machine.

Prerequisites​

Before you begin, ensure you have the following installed:

RequirementVersionDescription
Node.js>= 18.xJavaScript runtime
npm>= 9.xPackage manager
MongoDB>= 5.0Database (or MongoDB Atlas)
Redis>= 6.xQueue and caching (optional but recommended)
TypeScript>= 5.xType 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 Methods​

There are two ways to install JifiJs:

The fastest way to create a new project:

# Create a new project (interactive mode)
npx create-jifijs my-project

# Or with automatic naming
npx create-jifijs

The installer will prompt you with several options:

  ╔═══════════════════════════════════╗
  ║                                   ║
  ║        Create JifiJs Project      ║
  ║                                   ║
  ╚═══════════════════════════════════╝

? Project name: my-jifijs-app
? Include tests? (Y/n) Yes
? Include docker-compose.yml? (Y/n) Yes
? Install dependencies now? (Y/n) Yes

✓ Downloading JifiJs template...
✓ Configuring package.json...
✓ Creating .env file...
✓ Installing dependencies...
✓ Initializing git repository...

✓ Project created successfully!

Then start developing:

# Navigate to project
cd my-project

# Configure environment variables
nano .env
# Update MongoDB URI, Redis, JWT secrets, etc.

# Start development server
npm run dev

This method:

  • Downloads the latest template from npm
  • Asks for your preferences (tests, Docker, dependencies)
  • Installs dependencies based on your choice
  • Creates a ready-to-use project structure
  • Initializes git repository with initial commit
  • Creates .env file from .env.example
  • Excludes unwanted files (dist, node_modules, coverage, etc.)

Method 2: Clone from GitHub (For Contributors)​

If you want to contribute or need the development version:

1. Clone the Repository​

git clone https://github.com/mrnjifanda/jifijs.git my-project
cd my-project

2. Install Dependencies​

npm install

This will install all required dependencies including:

  • Express.js 5.x
  • TypeScript 5.x
  • 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="JifiJs"
APP_URL=http://localhost:3000
FRONTEND_URL=http://localhost:5173

# Database
MONGODB_URI=mongodb://localhost:27017/jifijs
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="JifiJs"

# 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

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
astuce

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

Verify Installation​

Open your browser and navigate to:

You should see:

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

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 JifiJs 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 jifijs@njifanda.com