Muchas Framework

0.0.130 verified Thu Apr 23 auth: no javascript abandoned

Muchas is an opinionated microservice NodeJS framework designed to streamline and standardize application development by providing a cohesive, integrated ecosystem of established libraries. It leverages Express under the hood for building web applications, Mongoose for robust Object Data Modeling (ODM) with MongoDB databases, and `amqp.node` for efficient message brokering, encouraging use with RabbitMQ. The framework enforces a specific application structure and relies heavily on external configuration, utilizing `muchas.yml` for structured configuration and `.env` files for dynamic environment variables, which dictate crucial settings such as server ports, database connection URIs, and component loading paths. At version `0.0.130`, it signifies a project in its nascent or experimental stages, which implies that the APIs are highly unstable and prone to frequent, potentially undocumented breaking changes even between minor or patch releases. Its "WIP DOCUMENTATION" status further underscores this instability and suggests an irregular or effectively halted release cadence. Key differentiators include its strong opinions on how microservices should be built, providing out-of-the-box components for web servers, message brokers, scheduled routines, health monitoring, and an extensible logging system with built-in Elasticsearch integration. This approach aims to reduce boilerplate and enforce best practices across a suite of services, though it demands adherence to its specific architectural choices.

Common errors

error Error: listen EADDRINUSE: address already in use :::<port_number> ↓

cause Another process or another instance of Muchas Framework is already running on the configured web or health port.

fix

Change the 'SERVER_PORT' or 'DEBUG_PORT' in your .env or muchas.yml file, or ensure only one instance is running per port.

error ReferenceError: MuchasFramework is not defined ↓

cause Attempting to use CommonJS 'require' syntax for a library primarily designed for ESM 'import's, or an incorrect import path.

fix

Ensure your project is configured for ES modules and use 'import MuchasFramework from 'muchas-framework';' at the top of your file.

error MongoServerSelectionError: connect ECONNREFUSED <ip>:<port> ↓

cause The MongoDB server specified in DATABASE_URI is unreachable, not running, or its network configuration prevents connection.

fix

Verify the 'DATABASE_URI' in your .env or muchas.yml is correct and that the MongoDB instance is accessible from your application's environment.

error (amqp.node) Channel closed by server: 406 (PRECONDITION_FAILED) - parameters for queue '<queue_name>' in vhost '/' are different. ↓

cause Attempting to connect to a RabbitMQ queue with parameters (e.g., durable, exclusive, arguments) that conflict with an existing queue of the same name.

fix

Ensure all consumers and producers define queue parameters consistently, or delete and recreate the queue if it's safe to do so for development.

Warnings

breaking The package is pre-1.0 (version 0.0.130) and actively states "WIP DOCUMENTATION". This implies an unstable API with frequent, undocumented breaking changes that can occur between patch versions. ↓

fix Treat all minor and patch updates as potentially breaking; review source code changes thoroughly and prepare for API adjustments.

gotcha Heavy reliance on external configuration via 'muchas.yml' and '.env' files for fundamental settings like ports, database URIs, and component paths. Misconfiguration will lead to runtime errors or unexpected behavior. ↓

fix Always ensure 'muchas.yml' and '.env' are correctly configured and present in the application's working directory. Use schema validation or environment variable checks to prevent issues.

gotcha The project appears to be unmaintained or abandoned, with the last publish over four years ago. This means there will be no security updates, bug fixes, or feature enhancements from the original authors. ↓

fix Consider migrating to an actively maintained framework. If continued use is necessary, be prepared to fork and maintain the codebase internally, especially for security vulnerabilities in its underlying dependencies.

gotcha The framework uses a global initialization pattern (MuchasFramework.init()), which can make testing and mocking difficult without careful design patterns or explicit framework support for dependency injection. ↓

fix When writing tests, consider how to reset the framework's state or provide mocks for its internal components. Look for any exposed APIs for dependency injection or framework lifecycle management.

Install

npm install muchas-framework

yarn add muchas-framework

pnpm add muchas-framework

Imports

MuchasFramework
wrong
```
const MuchasFramework = require('muchas-framework');
```
correct
```
import MuchasFramework from 'muchas-framework';
```
This is the primary default export of the framework for initialization. It ships TypeScript types and is designed for ESM environments, making CommonJS require() syntax generally incorrect or unsupported.
Web
wrong
```
import Web from 'muchas-framework/lib/web';
```
correct
```
import { Web } from 'muchas-framework';
```
Accesses the integrated Express web server component for direct configuration or extension. It is exposed as a named export from the main package.
Logger
wrong
```
import { createLogger } from 'muchas-framework';
```
correct
```
import { Logger } from 'muchas-framework';
```
Accesses the framework's configured logging utility. It is exposed as a named export from the main package, not typically via a factory function.
Broker
wrong
```
import { BrokerService } from 'muchas-framework';
```
correct
```
import { Broker } from 'muchas-framework';
```
Accesses the AMQP message broker component for advanced message queue and RPC operations. It is exposed as a named export from the main package.

Quickstart

This quickstart initializes the core Muchas Framework instance, demonstrating the asynchronous setup process required before the application can handle requests or messages, typically relying on external configuration files.

import MuchasFramework from 'muchas-framework';

(async () => {
  try {
    console.log('Initializing Muchas Framework...');
    await MuchasFramework.init();
    console.log('Muchas Framework initialized successfully.');
    // In a real application, you'd start listening for messages or requests here.
    // Example: MuchasFramework.web.start() or register broker consumers.
    // Note: The framework typically relies on configuration files (muchas.yml, .env)
    // for port numbers, database URIs, etc.
  } catch (error) {
    console.error('Failed to initialize Muchas Framework:', error);
    process.exit(1);
  }
})();