waw Framework

waw is a minimal Node.js (≥ 24) platform that loads modules and either:

• executes a CLI command exposed by modules (cli.js), or
• boots the runtime by sequentially loading each module’s index.js.

The core is intentionally small. It does not implement application frameworks, routing, databases, generators, or business logic — modules do.

---

Philosophy

• Tiny core — only module discovery, dependency install, ordering, CLI dispatch, runtime bootstrap
• Modules first — all behavior comes from modules
• Explicit over magic — behavior is defined by files (module.json, cli.js, index.js)
• Sync by default — dependency installation and module load preparation are deterministic

If a feature is not implemented by a module, it does not exist.

---

Requirements

• Node.js ≥ 24
• npm available in PATH

---

Installation

npm install -g waw

---

Project structure (minimal)

project/
├── config.json
├── server.json          (optional)
├── server/              (default local modules folder; configurable)
│   ├── my-module/
│   │   ├── module.json
│   │   ├── index.js     (optional runtime entry)
│   │   └── cli.js       (optional CLI commands)

---

How waw works

1) Configuration & module discovery

On startup, waw reads config from (merged, later wins):

1. Global waw/config.json
2. Global waw/server.json
3. Project ./config.json
4. Project ./server.json

Then it discovers modules:

• Local modules: directories under /<project>/<config.server>

  • If config.server is not set and a server/ folder exists, it uses "server".

• Global modules: declared in config.modules and fetched into the globally installed waw package under waw/server/<name>.

Global module fetch behavior:

• config.modules is interpreted as a map of { <moduleName>: <orgKey> }.

• Supported orgKey values are:

  • waw → https://github.com/WebArtWork/waw-{NAME}.git
  • itkp → git@github.com:IT-Kamianets/waw-{NAME}.git

• If a required global module directory is missing, waw performs a destructive force sync of that repo into waw/server/<name>.

Fallback behavior:

• If no modules are found at all, waw force-syncs and loads a global module named core from the waw org pattern.

Project-type auto modules:

• If the project contains one of these marker files:

  • angular.json → loads global module angular
  • react.json → loads global module react
  • vue.json → loads global module vue
  • wjst.json → loads global module wjst

• Each is fetched from the waw org pattern if missing.

Note: In this repository, the loader contains only these mechanics. Any application/framework behavior must be implemented by modules.

---

2) Module definition (module.json)

Each module is a folder containing module.json.

Supported fields used by this loader include:

• dependencies: an object of npm dependencies to install into the module directory
• before / after: ordering constraints (string or array; supports "*")
• priority: numeric priority used only when ordering constraints form a cycle

The loader normalizes and augments module metadata at load time:

• m.__root / m.rootPath: absolute path to the module folder
• m.__name: directory name (module name)
• m.__global: boolean whether module is global
• m.files: snapshot list of files under the module directory (excluding node_modules and .git)

---

3) Dependencies

Modules may declare npm dependencies inside module.json:

{
  "dependencies": {
    "express": "^4.19.0"
  }
}

Behavior:

• Dependencies are installed synchronously during module loading.

• Installation is performed into <moduleRoot>/node_modules.

• waw installs all declared deps in a single npm i call using:

  • --no-save --no-package-lock --no-audit --no-fund --loglevel=error
  • --legacy-peer-deps

• The loader checks installed versions with a small semver matcher supporting:

  • exact x.y.z
  • ^x.y.z, ~x.y.z
  • >=x.y.z
  • * / latest

No package.json is created inside modules by the loader.

---

4) Module ordering (before / after)

Modules may define ordering rules in module.json:

{ "before": "*" }

{ "after": "core", "before": "*" }

Rules:

• before / after accept a string or an array
• "*" means “all modules except those explicitly constrained in the opposite direction”
• Ordering is a stable topological sort based on discovery order
• If constraints produce a cycle, waw falls back to sorting by priority (descending)

---

5) CLI commands (cli.js)

A module may provide CLI commands by including a file named exactly cli.js.

Example:

// cli.js
module.exports.love = function (waw) {
  console.log("waw loves you :)");
  process.exit(0);
};

Run:

waw love

Dispatch rules:

• waw reads the raw command from process.argv[2].

• CLI files are scanned from the last module to the first (later modules override earlier ones).

• Only files with base name cli.js are considered (not *.cli.js).

• Matching is attempted in this order:

  1. exact key match with raw command (ex[cmdRaw])
  2. exact key match with lowercased command (ex[cmd])
  3. case-insensitive scan of exported keys

• cli.js may export:

  • an object of command functions, and/or

  • a function (cmdRaw, waw) => boolean|void

    • If it returns false, it is treated as “not handled” and waw continues scanning.
    • Any other return value (or no return) is treated as handled.

When a command is executed, the command receives a context object (see below) and the process is expected to exit if appropriate.

---

6) Runtime (index.js)

If no CLI command is handled, waw starts the runtime using nodemon.

Nodemon runs util.runtime.js and watches:

• Project:

  • <project>/server
  • <project>/angular.json
  • <project>/react.json
  • <project>/vue.json
  • <project>/config.json

• Global waw install:

  • <waw>/server
  • <waw>/config.json

When runtime starts, waw sequentially loads each module’s index.js:

• If <moduleRoot>/index.js exists and exports a function, it is called as await func(waw).
• Errors are caught and printed; loading proceeds to the next module.

---

The waw context

Every CLI command and runtime module receives a shared waw object containing:

Core properties

• argv — CLI args after waw (process.argv.slice(2))
• projectPath — current working directory
• modulesPath — resolved modules directory in the project (defaults to <project>/server)
• wawPath — directory of the globally installed waw package
• wawModulesPath — <wawPath>/server
• configPath / configServerPath — project config file paths
• wawConfigPath / wawConfigServerPath — global config file paths
• config — merged config snapshot (global + project)
• projectType — one of: angular | react | vue | wjst | waw | ""

FS helpers

• exists(...parts)
• isFile(...parts)
• isDir(...parts)
• ensureDir(...parts)
• rm(...parts)
• readText(path, fallback?)
• writeText(path, data)
• readJson(path, fallback?)
• writeJson(path, obj, pretty = true)
• readWrite(fromPath, toPath, replaceMap)

Utilities

• terminal — interactive CLI helper (ask/confirm/choose + spinner)
• git — git workflows utility (init, attach, forceSync, publish, etc.)

Events

• emit(event, ...args)
• on(event, fn)
• once(event, fn)
• off(event, fn)

Extra fields injected by the loader

When running CLI commands, waw injects these additional fields:

• modules — ordered list of loaded modules
• module — current module object
• module_root — current module root path
• module_config — current module config object (module.json content + loader metadata)

---

What waw is not

• Not a backend framework
• Not tied to Express/MongoDB/etc.
• Not a generator by default
• Not async-heavy
• Not opinionated

Those belong in modules.

---

Contributing

Contributions are welcome:

• Improve the loader (keep it small)
• Improve documentation
• Create modules
• Report bugs

See CONTRIBUTING.md.

---

License

MIT © Web Art Work