Getting Started
Install @kumbatio/energy-system, create an engine, and resolve your first strategy.
Install the package, create an engine, resolve a strategy. That's the whole loop - everything else in the SDK builds on it.
Install
pnpm add @kumbatio/energy-systemThe core has zero runtime dependencies. React (>=19.2) is an optional peer dependency, only needed if you import @kumbatio/energy-system/react. The floor is 19.2 rather than 19 because the React entry point uses <Activity>, which landed in 19.2.
First engine
import {
createEnergyEngine,
uiVisibilityStrategy,
notificationStrategy,
} from '@kumbatio/energy-system'
import { localStoragePersistence } from '@kumbatio/energy-system/persistence'
const engine = createEnergyEngine({
initialLevel: 75,
persistence: localStoragePersistence(),
})
// The user says "I'm at steady capacity now"
engine.setLevel(50)
// Resolve behavior from that state
const ui = engine.resolve(uiVisibilityStrategy)
const notifications = engine.resolve(notificationStrategy)
ui.sidebar // true at 50
notifications.priorityThreshold // 'high' at 50 - only high+ gets throughsetLevel() updates subscribers synchronously; persistence runs in the background with retry. Call await engine.flush() when a workflow must wait for durable storage.
What you get
The package ships five entry points:
.
./react
./dom
./persistence
./css
| Entry point | What's in it |
|---|---|
. (core) | Engine, levels, strategies, presence, focus sessions, notification gate, deferral, metrics, compatibility helpers. Runs in any JS/TS runtime. |
./react | EnergyProvider, hooks, <EnergyGate>, <EnergyIndicator>. |
./dom | applyEnergyLevel, readEnergyLevel, observeEnergyLevel - data attributes + CSS variables for any framework (or none). |
./persistence | localStoragePersistence, memoryPersistence. |
./css | Reference stylesheet implementing the UI visibility strategy and presence attributes. |