StaticFlux

Static core, flux implementations. StaticFlux is a client-side TypeScript framework for large single-page web applications — the kind that span many teams, many packages and possibly many repos. It is a small, stable core of contracts and primitives, plus an ecosystem of building blocks that plug into it. Every package is usable on its own; they work best together.

Built on Lit (web components) and MobX 7 (in-thread reactivity). Client-only: there is no server runtime — backend contracts are typed, and the example app runs against mocks.

Documentation site: https://akriti2591.github.io/staticflux/

import { token, unit } from '@staticflux/core';
import { bootApp, runtimeUnits } from '@staticflux/runtime';

export interface Greeter { greet(name: string): string }
export const GreeterToken = token('hello/greeter').type<Greeter>();

export const greeterUnit = unit({
  id: 'hello/greeter-unit',
  provides: GreeterToken,       // what it offers
  scope: 'app',                 // how long it lives
  create: (): Greeter => ({ greet: (name) => `Hello, ${name}!` }),
});

const booted = await bootApp({ units: [...runtimeUnits, greeterUnit] });   // Result<App>, never throws
if (booted.ok) {
  const greeter = await booted.value.injector.get(GreeterToken);              // Result<Greeter>
}

The philosophy, in short

• Inversion of control everywhere. Units declare what they require and provide; the injector hands dependencies in. The core never knows about features — features and framework packages contribute through the same typed contribution points.
• Declarations, not magic strings. Tokens, flags, metrics, routes, capabilities and errors are typed values. Misconfiguration is a compile-time or CI error.
• Scopes and lifecycles. Every lifecycle is a typed state machine; every resource lives in a disposal scope with an AbortSignal. Leaving a state cleans up.
• Plugins, not branches. Experiments and modes are alternate bindings and separate features — never if/else in feature code. Composition over inheritance (one level: Lit's base element).
• One telemetry fabric. DI, navigation stages, chunks, requests, gate decisions, workers and renders all emit OpenTelemetry-shaped spans; journeys, budgets and devtools are consumers.
• Performance first. Everything lazy by default, budgets enforced in CI that only ratchet tighter.
• Agent-first codebase. Explicit and shallow, every package documented in an AGENTS.md, every error a stable code with a fix, rules enforced by tooling.
• Client gating is UX, not security. The server re-checks every request.

Read more: Philosophy · Before / After · docs/REQUIREMENTS.md

Packages

A package may import only lower layers — core < runtime < vertical < ui < shell < (feature) < app — through its declared dependencies, checked by pnpm lint:boundaries. Each links to its AGENTS.md (purpose, public API by file, rules, budgets).

Core

Package
@staticflux/core	Tokens, units, the readiness-aware injector, scopes, Result, Tasks, state machines, telemetry, reactivity port (≤ 7.5 KB boot surface)

Runtime

Package
@staticflux/runtime	App supervisor, app & feature lifecycles, resource manager, frame scheduler; memory budgets (/memory)
@staticflux/storage	One async key-value interface over any backend, with composable middleware

Verticals

Package
@staticflux/platform	Capability-based platform facts, host modes, form factors, app profile, isolation policy
@staticflux/config	Typed flags, layered resolution, OpenFeature-compatible providers, variant bindings
@staticflux/auth	Identity providers, session lifecycle, multi-tab sync, single-flight refresh, token broker
@staticflux/gate	Facts → policies → compiled decision tables; explainable decisions; meters (credits, quotas)
@staticflux/data	Transports, resources with SWR and epochs, the single retry layer, schema-first stores, user-data slices
@staticflux/router	Async 13-stage navigation pipeline, typed routes, exit guards, view sub-routes, routable dialogs
@staticflux/urlstate	URL-state kinds and owners, declared bindings, URL ⇄ store sync, consume-once intents
@staticflux/handoff	State that survives reloads, redirects, tabs and embeds, with declared lifetimes

UI and shell

Package
@staticflux/ui	Lit components that self-inject render / lazy / functional deps; one render pass per frame; typed theme contract → CSS custom properties, densities, reduced motion (/theme)
@staticflux/kit	UI kit: themed Lit components (buttons, fields, slider, menus, popovers, tabs, toolbar, dock, inspector, tree, command palette) wired to messaging and capabilities
@staticflux/messaging	One surface manager: dialogs, sheets, popovers, toasts, banners, coach marks — scope-bound, arbitrated
@staticflux/surface	DOM / Canvas2D / WebGL / WebGPU / HTML-in-Canvas surfaces, render workers, input forwarding; GPU raster backend port with tiles and layers (/raster), text input over EditContext or a hidden textarea (/text-input), image scaling and PNG (/image)
@staticflux/shell	Slots, design-token themes, workspaces, command palette, skip links, error boundaries; declarative layout specs over registered contributions, validated, gated and applied as minimal animated diffs (/spec)
@staticflux/devtools	Devtools on the telemetry fabric: boot waterfall, journeys, DI graph, decisions, violations (dev only)

Tooling (build and test time only)

Package
@staticflux/testkit	Test injector with overrides, fake time, fake session, bootTestApp, shared contract suites
@staticflux/sf	CLI: graph check, lint rules, error catalog, budget ratchets, AGENTS.md sync, route and manifest checks
@staticflux/vite-plugin	Vite 8 (default bundler): logical chunks, sf-manifest.json, preloads, precache list, budgets
@staticflux/rspack-plugin	Rspack / Module Federation 2.0: the same manifest, remotes as logical chunks, singleton checks

Apps: apps/studio — the example app (below) · apps/instaflow — Instaflow, a local-first design, video and flow editor built on StaticFlux (in development; plans in docs/instaflow) · site — the documentation site, itself built with StaticFlux.

Quick start

Requirements: Node ≥ 22 and pnpm 10 (corepack enable picks up the pinned version).

git clone https://github.com/akriti2591/staticflux.git
cd staticflux
pnpm install
pnpm build          # tsc -b: every package → dist/
pnpm test           # vitest + happy-dom; tests import packages from source
pnpm check          # the full CI gate: build, typecheck, test, boundaries, sf lint, error catalog, size budgets, licenses

Run the Studio example

Studio is an AI-assisted mixed-media document editor that composes every vertical against mock services: agentic chat, a document worker with co-editing, free vs premium gating with credits, guest vs signed-in, an expert workspace and per-mode editor variants.

cd apps/studio
npx vite                                # dev server; packages resolve from source (no build needed)
npx vite build                          # production build + sf-manifest.json, sf-build-report.json
cd ../.. && npx vitest run apps/studio  # headless integration tests

Try /studio/doc/1?panel=chat&prompt=Add%20an%20image, /onboarding/step/1, /settings, ?sf-mode=web:compact and ?sf-debug. See apps/studio/README.md for the architecture map and its adapters.

Run the documentation site

pnpm build                              # the site's build-time renderer reads packages' dist
pnpm --filter @staticflux/site dev      # http://localhost:5173/staticflux/
pnpm --filter @staticflux/site build    # → site/dist

Documentation

Documentation site	Philosophy, before/after examples, getting started, guides per area, package reference
AGENTS.md	The rules, for humans and AI agents (each package has its own)
CONTRIBUTING.md	Dev setup, repo layout, rules explained, adding packages and features, the pnpm check gate
docs/REQUIREMENTS.md	What the framework must do (requirement IDs like R7.14)
docs/ARCHITECTURE.md	Layers, packages, contracts
docs/LIFECYCLES.md	Every state machine, valid transitions, invariants and error codes
docs/FEATURE-NEEDS.md	The example app's needs every API traces to
docs/errors.json	Machine-readable error catalog (pnpm errors)
docs/research/prior-art.md	Prior-art survey behind the design

Publishing the site (repository owner)

The site deploys from .github/workflows/pages.yml on every push to main (and on manual dispatch). One-time setup: in the repository settings, open Pages → Build and deployment → Source and select GitHub Actions. The site is served at https://akriti2591.github.io/staticflux/ (the Vite base is /staticflux/; change it in site/src/build/site.ts if the repository is renamed or a custom domain is used).

License

MIT © akriti2591 and StaticFlux contributors.