MwalaJS Framework Documentation

MwalaJS Framework Documentation

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:

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:

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

Issue Solution
mwala not recognized Recheck path, restart terminal
File won’t extract Install 7-Zip or WinRAR
Node.js not found Download from official site
Permission denied Use sudo or check permissions

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

Command Description
mwala create-project <name> Create a new project
mwala init Initialize MwalaJS
mwala serve Run in development mode
mwala help Display help
mwala generate model <name> Generate model
mwala generate controller <name> Generate controller
mwala generate route <name> Generate route
mwala generate view <name> Generate view
mwala generate midware <name> Generate middleware
mwala create-db Create database
mwala create-table <name> Create table
mwala drop-table <name> Drop table
mwala migrate all Run all migrations
mwala rollback all Undo migrations

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:

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.

About MwalaJS

MwalaJS is developed by Hekima Ambalile Mwala and the MwalaJS Team. It's open-source under the MIT License, aimed at simplifying Node.js development for beginners and experts alike.

Security Notes

  • Keep dependencies updated with npm update.
  • Sanitize user inputs to prevent vulnerabilities.
  • Run npm audit regularly for security checks.
  • Use HTTPS in production.
  • Implement authentication middleware.

License

MIT License © 2025 Hekima Mwala and MwalaJS Team. All rights reserved for contributions.

MwalaJS Release Downloads

For versions below 1.0.2, download .EXE, .ZIP, or .RAR. For latest, use NPM.

Version 1.0.1

File Type Description Download
ZIP Latest release ZIP Download
RAR Latest release RAR Download

Version 1.0.0

File Type Description Download
EXE Installer (.exe) Download
ZIP v1.0.0 ZIP Download
RAR v1.0.0 RAR Download

MwalaJS CLI Documentation

Version: 1.1.0

Last Updated: December 29, 2025

MwalaJS CLI is a versatile command-line tool designed to streamline JavaScript project development. It offers features for project creation, code generation, server management, and extensive database operations supporting MySQL, PostgreSQL, SQLite, and MongoDB. This documentation provides an in-depth guide to help developers, teams, and contributors fully utilize the tool's capabilities.

The CLI is built with Node.js and ESM modules, ensuring modern, efficient performance. Whether you're a beginner setting up your first project or an advanced user managing complex database migrations, MwalaJS CLI has you covered.

Introduction to MwalaJS

MwalaJS is a lightweight, flexible CLI tool tailored for JavaScript developers. It simplifies common tasks such as creating projects, generating boilerplate code, managing servers, and handling database operations. Inspired by frameworks like Express and Laravel, MwalaJS aims to provide a seamless development experience without the overhead of heavy dependencies.

Key Features:

  • Project initialization and setup
  • Code generation for models, controllers, routes, views, and middleware
  • Server management with live reloading support
  • Interactive database configuration for multiple DB types (MySQL, PostgreSQL, SQLite, MongoDB)
  • Over 20 database commands for table management, data import/export, backups, and maintenance
  • Migration system for schema changes
  • Cross-platform compatibility (Windows, macOS, Linux)
  • Extensible architecture for custom extensions

MwalaJS is ideal for web applications, APIs, and full-stack projects. It promotes best practices like modular code structure and secure database handling.

Tip: Always run mwala help in your terminal for a quick command reference.

Installation

To install MwalaJS CLI globally, use npm:

npm install -g mwalajs

Verify the installation:

mwala -v

Expected output: MwalaJS Version: 1.1.0

System Requirements:

  • Node.js v14 or higher
  • npm v6 or higher
  • For database operations: Corresponding DB server installed (e.g., MySQL 8.0+)
  • Windows users: Ensure MySQL bin directory is in PATH or use XAMPP/WAMP for auto-detection

If installing locally in a project:

npm install mwalajs --save-dev

Then run with npx: npx mwala help

Warning: Ensure your .env file is in the project root for database commands.

Updating MwalaJS:

npm update -g mwalajs

Check for updates regularly to get new features and bug fixes.

Getting Started

After installation, start by creating a new project:

mwala create-project

This sets up a basic structure with folders for models, controllers, routes, views, and middlewares.

Initialize MwalaJS in an existing project:

mwala init

Configure your database:

mwala create-db

This interactively prompts for DB type, name, host, user, and password, saving to .env.

Start the server:

mwala serve

Open http://localhost:3000 (or your configured port) to see the app running.

For a quick test, generate a model:

mwala generate model User

This creates models/User.mjs with a basic export.

Example Workflow

  1. Create project: mwala create-project
  2. Setup DB: mwala create-db
  3. Generate code: mwala generate controller Home
  4. Run server: mwala serve
  5. Manage DB: mwala db:table list

This workflow can be expanded for larger applications, including API development and data migrations.

General Commands

These are basic commands for version and help information.

Command Description Example
mwala -v or mwala --version Displays the current version of MwalaJS CLI. mwala -v → MwalaJS Version: 1.1.0
mwala help or mwala h Shows the full help menu with all available commands. mwala help → Prints the command list

These commands are essential for quick checks and navigation. Always refer to help when unsure about command syntax.

Project Management Commands

Commands for creating and initializing projects.

Command Description Example
mwala create-project Creates a new MwalaJS project with basic folder structure and files. mwala create-project → Sets up models, controllers, etc.
mwala init Initializes MwalaJS in the current directory, adding necessary config files. mwala init → Prepares an existing folder for MwalaJS

When creating a project, MwalaJS generates a skeleton app.mjs for entry point. Customize it as needed for your application.

Example: Creating a New Project

mwala create-project
cd my-project
mwala init
mwala serve

This sets up and starts a basic server.

Advanced tip: Use mwala init in monorepos for multiple sub-projects.

Running the Application

Command to start the MwalaJS server.

Command Description Example
mwala serve Starts the application by spawning node app.mjs, with signal handling for clean shutdown. mwala serve → Runs the server

The server listens on the port specified in .env or defaults to 3000. It supports hot reloading with additional tools like nodemon (install separately).

Tip: Use nodemon -x "mwala serve" for auto-restart on file changes.

Troubleshooting: If the port is in use, change PORT in .env and restart.

Code Generation Commands

Commands to generate boilerplate code for various components.

Command Description Example
mwala generate model <name> Creates a new model file in models/ folder. mwala generate model User → models/User.mjs
mwala generate controller <name> Creates a controller with a basic getPage method. mwala generate controller Home → controllers/Home.mjs
mwala generate route <name> Creates a route file with Router setup. mwala generate route Api → routes/Api.mjs
mwala generate view <name> Creates a basic HTML view file. mwala generate view Index → views/Index.html
mwala generate midware <name> Creates a middleware function. mwala generate midware Auth → middlewares/Auth.mjs

Generated files are ESM modules (.mjs) for modern JavaScript support. They include basic templates that you can extend.

Example: Generating a Full Feature

mwala generate model User
mwala generate controller User
mwala generate route User
mwala generate view User

This creates a complete CRUD skeleton for 'User'.

Customization: Edit the generated files to add logic, e.g., database interactions in models.

Database Setup Commands

Commands for configuring and reconfiguring the database.

Command Description Example
mwala create-db Interactively creates and connects to a database, saving config to .env. mwala create-db → Prompts for DB type, name, etc.
mwala db:config Reconfigures the database settings interactively. mwala db:config → Updates .env

Supported DB types: mysql/my, postgresql/pg, mongodb/mn, sqlite/sq. The CLI handles creation if the DB doesn't exist.

Warning: Backup .env before reconfiguring to avoid data loss.

Advanced: For custom ports, edit .env directly after initial setup.

Database Operations Commands

MwalaJS provides over 20 commands for database management. All require a configured .env.

Table Management

Command Description Example
mwala db:table list Lists all tables in the database. mwala db:table list → Shows tables
mwala db:table describe <name> Shows structure of a table (columns, types). mwala db:table describe users → Table schema
mwala db:table count <name> Counts rows in a table. mwala db:table count users → Row count
mwala db:table truncate <name> Empties a table (with confirmation). mwala db:table truncate temp → Clears data
mwala db:table rename <old> <new> Renames a table. mwala db:table rename old_users new_users
mwala db:table copy <src> <dest> Copies table structure and data. mwala db:table copy users users_backup
mwala db:table exists <name> Checks if a table exists. mwala db:table exists users → Exists or not

Data & Backup

Command Description Example
mwala db:backup Creates a timestamped database backup. mwala db:backup → backup-dbname-timestamp.sql
mwala db:restore <file.sql> Restores from a backup file. mwala db:restore backup.sql
mwala db:export <table> <file.csv> Exports table to CSV. mwala db:export users users.csv
mwala db:import <file.csv> <table> Imports CSV into table. mwala db:import data.csv users
mwala db:seed <seedFile.mjs> Runs a seed file to populate data. mwala db:seed seeds/initial.mjs

Maintenance & Stats

Command Description Example
mwala db:size Shows database size. mwala db:size → Size in MB
mwala db:indexes <table> Lists indexes on a table. mwala db:indexes users
mwala db:vacuum Optimizes the database (SQLite/PostgreSQL). mwala db:vacuum
mwala db:connections Shows active connections. mwala db:connections
mwala db:kill-connections Kills other connections (with confirmation). mwala db:kill-connections
mwala db:drop-all-tables Drops all tables (dangerous, with double confirmation). mwala db:drop-all-tables

Database commands are cross-DB compatible where possible. For MongoDB, 'tables' are 'collections'.

Example: Database Workflow

mwala db:table list
mwala db:backup
mwala db:size

This lists tables, backs up, and checks size.

Security note: Use .gitignore for .env to protect credentials.

Migration Commands

Commands for managing database schema changes.

Command Description Example
mwala migrate all Runs all pending migrations. mwala migrate all → Applies changes
mwala rollback last Rolls back the last migration. mwala rollback last → Reverts last change

Migrations are stored in migrations/ folder. Use mwala generate migration <name> to create new ones (if extended).

Warning: Always backup before migrating in production.

Advanced Usage

Extend MwalaJS by adding custom commands to the CLI script. Integrate with other tools like Docker for containerization.

Custom Environment Variables:

  • PORT: Server port (default 3000)
  • DB_TYPE, DB_NAME, etc.: Database config

For CI/CD, use commands in scripts: mwala migrate all && mwala serve

Performance tip: For large databases, use batch operations in imports/exports to avoid memory issues.

Security best practices: Use environment variables for secrets, validate inputs in generated code, and use prepared statements for DB queries.

Examples and Tutorials

Tutorial 1: Building a Simple API

mwala create-project
mwala generate model Todo
mwala generate controller Todo
mwala generate route Todo
mwala create-db
mwala db:table create todos
mwala db:seed seeds/todos.mjs
mwala serve

This sets up a Todo API with database.

Tutorial 2: Database Maintenance

mwala db:backup
mwala db:table truncate logs
mwala db:size
mwala db:vacuum

Maintains and optimizes the DB.

More tutorials available on the MwalaJS GitHub wiki (assumed).

Troubleshooting

Common Issues:

  • No .env found: Run mwala create-db to generate.
  • Command not found: Ensure global install and PATH set.
  • DB connection failed: Check credentials, server running, firewall.
  • Windows mysqldump error: Add MySQL bin to PATH or use XAMPP.
  • Permission denied: Run with sudo or check file permissions.

For bugs, report on GitHub with logs from node --trace-warnings.

Debug mode: Add console.logs in CLI script for tracing.

Contributing to MwalaJS

Fork the repo on GitHub, make changes, submit PR. Focus on new DB features or command enhancements.

Code Standards:

  • Use ESM imports
  • Async/await for promises
  • Error handling with try/catch
  • JSDoc comments for functions

Test locally with node cli.mjs help.

Contributors: Thank you for improving MwalaJS!

License

MwalaJS is open-source under the MIT License. Use, modify, distribute freely with attribution.

MIT License

Copyright (c) 2025 MwalaJS Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

MwalaJS CLI Documentation

Version: 1.1.0

Last Updated: December 29, 2025

MwalaJS CLI is a versatile command-line tool designed to streamline JavaScript project development. It offers features for project creation, code generation, server management, and extensive database operations supporting MySQL, PostgreSQL, SQLite, and MongoDB. This documentation provides an in-depth guide to help developers, teams, and contributors fully utilize the tool's capabilities.

The CLI is built with Node.js and ESM modules, ensuring modern, efficient performance. Whether you're a beginner setting up your first project or an advanced user managing complex database migrations, MwalaJS CLI has you covered.

Introduction to MwalaJS

MwalaJS is a lightweight, flexible CLI tool tailored for JavaScript developers. It simplifies common tasks such as creating projects, generating boilerplate code, managing servers, and handling database operations. Inspired by frameworks like Express and Laravel, MwalaJS aims to provide a seamless development experience without the overhead of heavy dependencies.

Key Features:

  • Project initialization and setup
  • Code generation for models, controllers, routes, views, and middleware
  • Server management with live reloading support
  • Interactive database configuration for multiple DB types (MySQL, PostgreSQL, SQLite, MongoDB)
  • Over 20 database commands for table management, data import/export, backups, and maintenance
  • Migration system for schema changes
  • Cross-platform compatibility (Windows, macOS, Linux)
  • Extensible architecture for custom extensions

MwalaJS is ideal for web applications, APIs, and full-stack projects. It promotes best practices like modular code structure and secure database handling.

Tip: Always run mwala help in your terminal for a quick command reference.

Installation

To install MwalaJS CLI globally, use npm:

npm install -g mwalajs

Verify the installation:

mwala -v

Expected output: MwalaJS Version: 1.1.0

System Requirements:

  • Node.js v14 or higher
  • npm v6 or higher
  • For database operations: Corresponding DB server installed (e.g., MySQL 8.0+)
  • Windows users: Ensure MySQL bin directory is in PATH or use XAMPP/WAMP for auto-detection

If installing locally in a project:

npm install mwalajs --save-dev

Then run with npx: npx mwala help

Warning: Ensure your .env file is in the project root for database commands.

Updating MwalaJS:

npm update -g mwalajs

Check for updates regularly to get new features and bug fixes.

Getting Started

After installation, start by creating a new project:

mwala create-project

This sets up a basic structure with folders for models, controllers, routes, views, and middlewares.

Initialize MwalaJS in an existing project:

mwala init

Configure your database:

mwala create-db

This interactively prompts for DB type, name, host, user, and password, saving to .env.

Start the server:

mwala serve

Open http://localhost:3000 (or your configured port) to see the app running.

For a quick test, generate a model:

mwala generate model User

This creates models/User.mjs with a basic export.

Example Workflow

  1. Create project: mwala create-project
  2. Setup DB: mwala create-db
  3. Generate code: mwala generate controller Home
  4. Run server: mwala serve
  5. Manage DB: mwala db:table list

This workflow can be expanded for larger applications, including API development and data migrations.

General Commands

These are basic commands for version and help information.

Command Description Example
mwala -v or mwala --version Displays the current version of MwalaJS CLI. mwala -v → MwalaJS Version: 1.1.0
mwala help or mwala h Shows the full help menu with all available commands. mwala help → Prints the command list

These commands are essential for quick checks and navigation. Always refer to help when unsure about command syntax.

Project Management Commands

Commands for creating and initializing projects.

Command Description Example
mwala create-project Creates a new MwalaJS project with basic folder structure and files. mwala create-project → Sets up models, controllers, etc.
mwala init Initializes MwalaJS in the current directory, adding necessary config files. mwala init → Prepares an existing folder for MwalaJS

When creating a project, MwalaJS generates a skeleton app.mjs for entry point. Customize it as needed for your application.

Example: Creating a New Project

mwala create-project
cd my-project
mwala init
mwala serve

This sets up and starts a basic server.

Advanced tip: Use mwala init in monorepos for multiple sub-projects.

Running the Application

Command to start the MwalaJS server.

Command Description Example
mwala serve Starts the application by spawning node app.mjs, with signal handling for clean shutdown. mwala serve → Runs the server

The server listens on the port specified in .env or defaults to 3000. It supports hot reloading with additional tools like nodemon (install separately).

Tip: Use nodemon -x "mwala serve" for auto-restart on file changes.

Troubleshooting: If the port is in use, change PORT in .env and restart.

Code Generation Commands

Commands to generate boilerplate code for various components.

Command Description Example
mwala generate model <name> Creates a new model file in models/ folder. mwala generate model User → models/User.mjs
mwala generate controller <name> Creates a controller with a basic getPage method. mwala generate controller Home → controllers/Home.mjs
mwala generate route <name> Creates a route file with Router setup. mwala generate route Api → routes/Api.mjs
mwala generate view <name> Creates a basic HTML view file. mwala generate view Index → views/Index.html
mwala generate midware <name> Creates a middleware function. mwala generate midware Auth → middlewares/Auth.mjs

Generated files are ESM modules (.mjs) for modern JavaScript support. They include basic templates that you can extend.

Example: Generating a Full Feature

mwala generate model User
mwala generate controller User
mwala generate route User
mwala generate view User

This creates a complete CRUD skeleton for 'User'.

Customization: Edit the generated files to add logic, e.g., database interactions in models.

Database Setup Commands

Commands for configuring and reconfiguring the database.

Command Description Example
mwala create-db Interactively creates and connects to a database, saving config to .env. mwala create-db → Prompts for DB type, name, etc.
mwala db:config Reconfigures the database settings interactively. mwala db:config → Updates .env

Supported DB types: mysql/my, postgresql/pg, mongodb/mn, sqlite/sq. The CLI handles creation if the DB doesn't exist.

Warning: Backup .env before reconfiguring to avoid data loss.

Advanced: For custom ports, edit .env directly after initial setup.

Database Operations Commands

MwalaJS provides over 20 commands for database management. All require a configured .env.

Table Management

Command Description Example
mwala db:table list Lists all tables in the database. mwala db:table list → Shows tables
mwala db:table describe <name> Shows structure of a table (columns, types). mwala db:table describe users → Table schema
mwala db:table count <name> Counts rows in a table. mwala db:table count users → Row count
mwala db:table truncate <name> Empties a table (with confirmation). mwala db:table truncate temp → Clears data
mwala db:table rename <old> <new> Renames a table. mwala db:table rename old_users new_users
mwala db:table copy <src> <dest> Copies table structure and data. mwala db:table copy users users_backup
mwala db:table exists <name> Checks if a table exists. mwala db:table exists users → Exists or not

Data & Backup

Command Description Example
mwala db:backup Creates a timestamped database backup. mwala db:backup → backup-dbname-timestamp.sql
mwala db:restore <file.sql> Restores from a backup file. mwala db:restore backup.sql
mwala db:export <table> <file.csv> Exports table to CSV. mwala db:export users users.csv
mwala db:import <file.csv> <table> Imports CSV into table. mwala db:import data.csv users
mwala db:seed <seedFile.mjs> Runs a seed file to populate data. mwala db:seed seeds/initial.mjs

Maintenance & Stats

Command Description Example
mwala db:size Shows database size. mwala db:size → Size in MB
mwala db:indexes <table> Lists indexes on a table. mwala db:indexes users
mwala db:vacuum Optimizes the database (SQLite/PostgreSQL). mwala db:vacuum
mwala db:connections Shows active connections. mwala db:connections
mwala db:kill-connections Kills other connections (with confirmation). mwala db:kill-connections
mwala db:drop-all-tables Drops all tables (dangerous, with double confirmation). mwala db:drop-all-tables

Database commands are cross-DB compatible where possible. For MongoDB, 'tables' are 'collections'.

Example: Database Workflow

mwala db:table list
mwala db:backup
mwala db:size

This lists tables, backs up, and checks size.

Security note: Use .gitignore for .env to protect credentials.

Migration Commands

Commands for managing database schema changes.

Command Description Example
mwala migrate all Runs all pending migrations. mwala migrate all → Applies changes
mwala rollback last Rolls back the last migration. mwala rollback last → Reverts last change

Migrations are stored in migrations/ folder. Use mwala generate migration <name> to create new ones (if extended).

Warning: Always backup before migrating in production.

Advanced Usage

Extend MwalaJS by adding custom commands to the CLI script. Integrate with other tools like Docker for containerization.

Custom Environment Variables:

  • PORT: Server port (default 3000)
  • DB_TYPE, DB_NAME, etc.: Database config

For CI/CD, use commands in scripts: mwala migrate all && mwala serve

Performance tip: For large databases, use batch operations in imports/exports to avoid memory issues.

Security best practices: Use environment variables for secrets, validate inputs in generated code, and use prepared statements for DB queries.

Examples and Tutorials

Tutorial 1: Building a Simple API

mwala create-project
mwala generate model Todo
mwala generate controller Todo
mwala generate route Todo
mwala create-db
mwala db:table create todos
mwala db:seed seeds/todos.mjs
mwala serve

This sets up a Todo API with database.

Tutorial 2: Database Maintenance

mwala db:backup
mwala db:table truncate logs
mwala db:size
mwala db:vacuum

Maintains and optimizes the DB.

More tutorials available on the MwalaJS GitHub wiki (assumed).

Troubleshooting

Common Issues:

  • No .env found: Run mwala create-db to generate.
  • Command not found: Ensure global install and PATH set.
  • DB connection failed: Check credentials, server running, firewall.
  • Windows mysqldump error: Add MySQL bin to PATH or use XAMPP.
  • Permission denied: Run with sudo or check file permissions.

For bugs, report on GitHub with logs from node --trace-warnings.

Debug mode: Add console.logs in CLI script for tracing.

Contributing to MwalaJS

Fork the repo on GitHub, make changes, submit PR. Focus on new DB features or command enhancements.

Code Standards:

  • Use ESM imports
  • Async/await for promises
  • Error handling with try/catch
  • JSDoc comments for functions

Test locally with node cli.mjs help.

Contributors: Thank you for improving MwalaJS!

License

MwalaJS is open-source under the MIT License. Use, modify, distribute freely with attribution.

MIT License

Copyright (c) 2025 MwalaJS Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Join the MwalaJS WhatsApp Support Group

Get real-time help from the community and developers.

Click here to join