Overview

MwalaJS is a lightweight and modular JavaScript framework designed for building scalable server-side applications using modern Node.js features. It follows the MVC (Model-View-Controller) pattern, making it easy to organize code for full-stack web applications. With built-in support for databases, routing, and middleware, MwalaJS accelerates development while keeping things simple and efficient.

Key Features:

• MVC Architecture for clean code separation
• CLI Tools for project scaffolding and management
• Database Migrations and Models
• Customizable Middleware
• Support for .mjs and .js modules
• Responsive and secure by design

Installation

Install MwalaJS globally to use CLI tools:

npm install -g mwalajs

If you're using it in a specific project, install locally:

npm install mwalajs

Note: In case of errors regarding missing fs-extra, install it manually:

npm install -g fs-extra

Note 2: MwalaJS is now an NPM package—no need to download .ZIP, .RAR, or .EXE files for versions 1.0.4 or above. Before creating a project, run npm init to create a package.json file. Ensure it includes:

"dependencies": {
  "mwalajs": "^1.0.5"
},
"type": "module"

These settings are crucial before running mwala serve.

Windows Installation Guide

What You’ll Need:

• A computer (Windows preferred)
• Internet connection
• Basic computer knowledge (copy, paste, extracting files)
• Node.js installed

Step-by-Step Instructions

1. Download MwalaJS: Go to https://mwalajs.biasharabora.com and download ZIP or RAR.
2. Extract the File: Right-click and extract to get the mwalajs folder.
3. Move to Program Files: Paste into C:\Program Files.
4. Add to Environment Variables: Edit system Path and add C:\Program Files\mwalajs.
5. Test: Open CMD and run mwala.

Linux Installation (Ubuntu/Debian/Fedora/Others)

1. Download: From the website, get ZIP or TAR.GZ.
2. Extract: Use unzip or tar -xvzf.
3. Move: sudo mv mwalajs /opt/
4. Make Executable: sudo chmod +x /opt/mwalajs/mwala.mjs
5. Create Symlink: sudo ln -s /opt/mwalajs/mwala.mjs /usr/local/bin/mwala
6. Test: Run mwala.

Troubleshooting

Installation Video Guide

Available Commands

Use the MwalaJS CLI to manage your projects efficiently. Run mwala help for a full list.

mwala create-project <projectName>  → Create a new MVC project.
mwala app.mjs                        → Start the main application file.
Database Commands:
  - mwala create-db                      → Create database.
  - mwala create-table <name>            → Create a table.
  - mwala drop-table <name>              → Drop a table.
  - mwala migrate all                    → Run migrations.
  - mwala rollback all                   → Undo last migration.

Code Generation:
  - mwala generate model <name>          → Generate a model file.
  - mwala generate controller <name>     → Generate a controller file.
  - mwala generate route <name>          → Generate a route file.
  - mwala generate view <name>           → Generate a view file.
  - mwala generate midware <name>        → Generate middleware.

mwala serve                          → Start local server.
mwala help                           → List all available commands.
mwala -v                             → Check version.
mwala init                           → Initialize MwalaJS in a project.
      

CLI Commands Table

Project Structure

MwalaJS follows a standard MVC structure for organization. The main entry point is app.mjs (use .mjs for ES modules; fallback to .js if needed, but app.mjs is required as MwalaJS points to it).

In other folders, use filename.mjs or filename.js if .mjs causes errors.

mwalajs-project/
├── app.mjs              # Main application entry point (must be .mjs)
├── migrations/          # Database migration files (e.g., migration001.js or .mjs)
├── models/              # Database models (e.g., UserModel.js or .mjs)
├── controllers/         # Application logic (e.g., UserController.js or .mjs)
├── routes/              # API routes (e.g., userRoutes.js or .mjs)
├── middlewares/         # Custom middleware (e.g., authMiddleware.js or .mjs)
├── config/              # Configuration files (e.g., database.js or .mjs, appSettings.js)
├── public/              # Static assets (CSS, JS, images)
│   ├── css/             # Stylesheets
│   ├── js/              # Client-side scripts
│   └── images/          # Images and icons
├── views/               # Template views for server-side rendering (e.g., index.html or .ejs)
├── package.json         # NPM dependencies and scripts
└── README.md            # Project documentation
      

Notes on File Extensions:

• Use .mjs for modern ES modules.
• If compatibility issues arise, switch to .js except for app.mjs.
• Example: controllers/UserController.mjs or UserController.js.

Examples

Here are some code examples to get you started with MwalaJS.

Creating a Simple Controller

// controllers/homeController.mjs
//homeController.mjs
export const homeController = {
  getHomePage: (req, res) => {
    res.render('index', { title: 'Welcome to MwalaJS MVC' });
  }

};


export const Steps = {
getSteps: (req, res) => {
  res.render('steps', { title: 'Welcome to MwalaJS MVC' });
}
};

export const welcome = {
  getwelcome: (req, res) => {
    res.render('welcome', { title: 'Welcome to MwalaJS MVC' });
  }
  };

  
  export const about = {
    getabout: (req, res) => {
      res.render('about', { title: 'Welcome to MwalaJS MVC' });
    }
    };
    

  

Defining a Route

// routes/homeRoutes.mjs
import mwalajs from 'mwalajs';
import { homeController,Steps,welcome,about } from '../controllers/homeController.mjs';

const router = mwalajs.Router(); // Corrected Router usage

router.get('/', homeController.getHomePage);
router.get('/steps',Steps.getSteps);
router.get('/welcome',welcome.getwelcome);
router.get('/about',about.getabout);


export { router as homeRoutes };

App Entry Point

// app.mjs
//app.mjs
import mwalajs from 'mwalajs';
import { homeRoutes } from './routes/homeRoutes.mjs';
import { fileURLToPath } from 'url';
import path from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Use mwalajs directly (it's an instance now)
mwalajs.set('view engine', 'ejs');
mwalajs.set('views', path.join(__dirname, 'views'));
// Serve static files correctly
mwalajs.useStatic(path.join(__dirname, 'public'));
// Use routes
mwalajs.use('/', homeRoutes);
mwalajs.use('/steps', homeRoutes);
mwalajs.use('/about', homeRoutes);
mwalajs.use('/welcome', homeRoutes);
mwalajs.get('/mwalajs-framework-documentation', (req, res) => {
  res.render('mwalajs-framework-documentation');
});

// Start server
const port = process.env.PORT || 2025;
mwalajs.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});

      
Generating a Model
      
Run mwala generate model User to create a model file.
      
// models/User.mjs
export class User {
  // Model logic here
}

EXAMPLE

import db from '../config/db.js';

export const getAllResources = async (filters = {}) => {
  let query = `
    SELECT r.*, u.fullname AS uploaded_by_name,
           c.name AS category_name,
           l.name AS level_name,
           s.subject_name
    FROM resources r
    LEFT JOIN users u ON r.uploaded_by = u.id
    LEFT JOIN categories c ON r.category_id = c.id
    LEFT JOIN levels l ON r.level_id = l.id
    LEFT JOIN subjects s ON r.subject_id = s.id
    WHERE 1=1
  `;
  const params = [];

  if (filters.category_id) {
    query += ' AND r.category_id = ?';
    params.push(filters.category_id);
  }
  if (filters.level_id) {
    query += ' AND r.level_id = ?';
    params.push(filters.level_id);
  }
  if (filters.subject_id) {
    query += ' AND r.subject_id = ?';
    params.push(filters.subject_id);
  }

  query += ' ORDER BY r.id DESC';
  const [rows] = await db.query(query, params);
  return rows;
};

export const getResourceById = async (id) => {
  const [rows] = await db.query('SELECT * FROM resources WHERE id = ?', [id]);
  return rows[0];
};

export const createResource = async (resource) => {
  const sql = `
    INSERT INTO resources
    (title, description, google_drive_link, category_id, level_id, subject_id, uploaded_by)
    VALUES (?, ?, ?, ?, ?, ?, ?)
  `;
  const params = [
    resource.title,
    resource.description,
    resource.google_drive_link,
    resource.category_id,
    resource.level_id,
    resource.subject_id,
    resource.uploaded_by
  ];
  await db.query(sql, params);
};

export const updateResource = async (id, resource) => {
  const sql = `
    UPDATE resources SET
      title = ?, description = ?, google_drive_link = ?,
      category_id = ?, level_id = ?, subject_id = ?
    WHERE id = ?
  `;
  const params = [
    resource.title,
    resource.description,
    resource.google_drive_link,
    resource.category_id,
    resource.level_id,
    resource.subject_id,
    id
  ];
  await db.query(sql, params);
};

export const deleteResource = async (id) => {
  await db.query('DELETE FROM resources WHERE id = ?', [id]);
};



      
More examples available in the official repository or by joining the support group.