mwalajs v1.1.0 and above documentation

Objectives: mwalajs v1.1.0 and above documentation

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