Module Manager

@versionzero/module-manager is a library that helps support partitioning NodeJS applications into modular subsystems that follow SOLID design principles. As applications grow in complexity, developers naturally break functionality into discrete modules to maintain code quality, testability, and team productivity. However, this architectural evolution introduces new challenges that can undermine the very benefits modularity is meant to provide.

One challenge that emerges from a decoupled software architecture is that an ever-increasing number of components needs to be interconnected and managed at runtime. What starts as a few cleanly separated modules quickly becomes a web of interdependencies that must be carefully orchestrated. Configuration becomes scattered across multiple locations, making it difficult to understand how the system fits together. Dependencies between modules create implicit coupling that breaks encapsulation. And coordinating the startup and shutdown of various subsystems becomes increasingly fragile as the dependency graph grows.

Application frameworks help by providing structure, but typically at the cost of introducing complex abstractions and dependencies. Heavy frameworks often dictate architectural patterns, lock you into specific ecosystems, and can make simple tasks unnecessarily complex. They solve the orchestration problem by imposing their own opinions about how your application should work.

ModuleManager takes a less-opinionated "opt-in" services approach, focusing on three main pain points that emerge organically from modular architectures:

• Configuration management - Allowing expressive configuration without breaking encapsulation
• Dependency injection - Connecting modules without tight coupling
• Lifecycle management - Coordinating startup, shutdown, and state transitions

Rather than replacing your architectural choices, ModuleManager uses a lightweight convention-based approach that does not require deep integration, and can be incrementally enhanced as your application grows, preserving the flexibility that drove you toward modularity in the first place.

Example

Let's write "Hello World" the hard way, splitting functionality across multiple modules, but then use ModuleManager to make it a little less painful:

import { ModuleManager, Schema } from '@versionzero/module-manager';

class AbstractGreetingProvider
{
  static moduleProvides = 'Greeting';

  getGreeting(capitalize) {
    if (!this.running) { throw new Error('not running'); }
    return capitalize ? this._greeting.toUpperCase() : this._greeting;
  }
  get _greeting() { throw new Error('not implemented'); }
  
  running = false;
  async start() { this.running = true;  }
  async stop()  { this.running = false; }
}

class Formal extends AbstractGreetingProvider
{
  get _greeting() { return 'hello' }
}

class Informal extends AbstractGreetingProvider
{
  get _greeting() { return 'hi' }
}

class Greeter
{
  static moduleInfo = {
    schema: new Schema()
      .property('provider',
        new Schema('Greeting').default('informal')
                              .required()
                              .meta('flagHint', 'p')
                              .meta('description', 'select a greeting type'))
      .property('capitalize',
        new Schema('boolean').default(false)
                             .meta('description', 'flag to request the greeting be capitalized')),
    register: [Formal, Informal]  // these will get registered as modules...
  }
  provider;
  capitalize;

  greet(recipient) {
    const greeting = this.provider.getGreeting(this.capitalize);
    console.log(`${greeting} ${recipient}`);
  }
}

class WelcomeApp
{
  static moduleInfo = {
    name: 'welcome',
    schema: new Schema()
      .property('recipient', new Schema('string').default('world'))
      .property('greeter', new Schema('Greeter').required())
  }
  recipient = 'everyone';
  greeter;

  async main() {
    this.greeter.greet(this.recipient);
  }
}

try {
  await new ModuleManager()
    .register(Greeter)
    .register(WelcomeApp)
    .run()
}
catch (error) {
  const cause = error.cause?.message ? ` (${error.cause.message})` : '';
  console.error(`${error.name}: ${error.message}${cause}`);
}

We get automatic configuration management, and module instances dependency-injected where requested:

% node welcome.js --help
Usage: welcome [options]
  --config (-C) [path|-]                    - load configuration from file (or - for stdin)
  --help (-h) [advanced]                    - display help information
  --recipient (-r) [string]                 - (default:world)
  --greeter-provider (-p) <formal|informal> - select a greeting type (required, default:informal)
  --greeter-capitalize (--gc) [true|false]  - flag to request the greeting be capitalized (default:false)
  
% node welcome.js -p formal
hello world
% export WELCOME_RECIPIENT=peeps
% node welcome.js -p informal --gc
HI peeps

Documentation

See https://docs.v0.net/module-manager for full documentation of the ModuleManager API and architecture.
Commented example code can be found at https://github.com/argh/module-manager/tree/main/examples.

Requirements

• ESM Modules
• Node 20.9.0+

See Also

ModuleManager is a higher-level abstraction built on @versionzero/configurator and @versionzero/schema, which both have their own documentation at https://docs.v0.net/.

License

Copyright 2026 Version Zero | github.com/argh

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this library except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.