awaforge

Getting started

Install a published package with npm, import it in the browser through an import map or in Bun and Node, and resolve your first module.

Every package documented on this site is published on the npm registry under the @awacloud scope. This page shows the three steps that are the same for all of them: install, import, resolve. It uses the framework, @awacloud/fw, as the example because every other package stands on it.

1. Install

npm install @awacloud/fw

The install line of each package, pinned to its published version, is on the package's Overview page (for example @awacloud/fw).

2. Import

The packages are plain ES modules with no build step and no bundler requirement. How you import them depends on where the code runs.

In the browser, through an import map

A statically served page maps the package name to the file the server exposes, and loads the framework's lockdown script first, as a classic script, so it runs before any other code:

<script src="/node_modules/@awacloud/fw/dist/build/sanity.min.js"></script>
<script type="importmap">
{ "imports": {
    "@awacloud/fw":  "/node_modules/@awacloud/fw/src/main.js",
    "@awacloud/fw/": "/node_modules/@awacloud/fw/src/"
}}
</script>
<script type="module">
    import fw from '@awacloud/fw';
    // ...
</script>

The paths assume node_modules/ is reachable from the HTTP document root; adjust the prefix to wherever you serve the package from. The trailing-slash entry ("@awacloud/fw/") maps every sub-path the package exposes, such as @awacloud/fw/core/modules.js.

In Bun or Node

Bun and Node resolve the package name through the package's own exports map, so a bare specifier is enough:

import fw from '@awacloud/fw';
import modules from '@awacloud/fw/core/modules.js';

Only the sub-paths a package declares in its exports map can be imported this way. A package documents the sub-paths it exposes in its README.

3. Resolve a module

The framework does not register its modules automatically. You compose a runtime explicitly, register the modules you ship, then resolve them by name. Five lines:

import fw from '@awacloud/fw';
import modules from '@awacloud/fw/core/modules.js';
const { runtime } = fw;
runtime.registerAll(modules);
const hex = runtime.resolve('hex');

runtime is the dependency-injection engine at the heart of the framework (ModuleRuntime): every module is a factory that declares the modules it depends on, and the runtime resolves them on demand. A module is a singleton: runtime.resolve always returns the same instance. Nothing loads until it is asked for.

console.log(hex.fromBytes(new Uint8Array([255, 0]))); // "ff00"

Where to go next

Each package's documentation lives on this site under its own pages:

  • the Overview is the package's README, with the install line and the link to its source directory;
  • the Guides tab holds the concept pages and recipes it ships;
  • the API tab, where a package ships one, mirrors its source tree one page per module.

The packages catalogue lists every published package by layer. The architecture page explains those layers, and the conventions page states what every published package guarantees to the code that consumes it.