Documentation
Introduction
What Alwatr is, how the ecosystem fits together, and why nano-packages.
Alwatr is a developer kit for building fast, production-grade web applications without adopting a heavyweight framework. It is not one library — it is an ecosystem of small, focused, zero-dependency TypeScript packages that compose into exactly as much (or as little) architecture as your project needs.
At its center is the Flux family — Signals, Actions, Directives, Bind, and Storage — a reactive, unidirectional data flow architecture inspired by the best ideas in React, Qwik, Solid, and Svelte, but with no Virtual DOM, no client-side hydration cost, and no build-step magic. Everything ships as tree-shakeable ESM and adds well under 15 KB, gzipped, to your bundle.
Why nano-packages?
Most of Alwatr lives under @alwatr/nanolib — roughly three dozen single-purpose packages (signal, action, directive, bind, logger, lazy, debounce, local-storage, and more), each independently publishable and completely dependency-free. Two curated bundles sit on top of them:
@alwatr/corere-exports the non-UI utilities every ECMAScript project needs — hashing, debouncing, fetch helpers, type guards — with no DOM assumptions, so it runs identically in the browser, Bun, or Node.@alwatr/fluxre-exports the browser-facing packages — signal, action, bind, directive, storage, plus a full re-export of@alwatr/fsm— as one cohesive UI architecture.
You can install a single nanolib package if that is all you need, or reach for @alwatr/flux when you want the whole system wired together. Nothing is forced on you; nothing you don't import ships in your bundle.
The Flux family
Every Flux primitive plugs into the same strict cycle: View → Action → Controller → State → View. Views read from signals and dispatch actions; controllers subscribe to actions and write to signals; signals notify the DOM back through directives and bind — never the other way around.
| Primitive | Role |
|---|---|
| Signals | Fine-grained reactive state: State, Computed, Effect, Event, Channel. |
| Actions | A typed, O(1) event bus wired to declarative on-<event> attributes. |
| Directives | Reusable, self-cleaning DOM behavior attached via plain HTML attributes. |
| Bind | Declarative, surgical text/value/attribute binding from a view model. |
| Storage | Persistent signals and SSR-safe hydration with zero flash of empty content. |
The wider ecosystem
Beyond the frontend story, the kit covers the rest of a typical stack:
| Package | What it is |
|---|---|
| @alwatr/fsm | A tiny, type-safe, reactive finite state machine engine built on Signals. |
| @alwatr/core | Cross-platform utilities: Lazy, Logger, hashing, debouncing, fetch, and more. |
| @alwatr/nanotron | A minimal-overhead micro API server framework for Bun and Node.js. |
| @alwatr/nitrobase | A blazingly fast, JSON-based in-memory database with file-backed persistence. |
| @alwatr/standard | Shared TypeScript and Prettier configuration, consumed via subpath imports. |
Where to go next
- New to the kit? Start with Getting Started — install the package and wire a signal, an action, and a directive together in a few minutes.
- Want the mental model first? Read Architecture & UDF for the full View → Action → Controller → State cycle and the Actor Model pattern.
- Already building? Jump straight to Signals or Actions & Events.