Show HN: Nucleus- web apps where document is the state, driven by CSS-like rules
nucleus.excom.dev
nucleus.excom.dev
The Nucleus stack is a few decoupled web technologies that work together as an implementation of the "ASO" architecture (stands for Adapter, State, Orchestrator). Practically, the goal of Nucleus is sophisticated, declarative, simple web apps with low-to-zero JS and no build process.
Architecturally, the "Orchestrator" is the primary innovation here. The original motivation: the web has never had an easy, native way to map data to the document. Every web framework primarily exists to fill this gap; most achieve it by keeping a copy of app state in JS memory and treating the DOM as a compile target. Yet CSS has quietly held templating-like abilities for a long time:
span::before { content: attr(data-text); }
"Adapters" are certain elements (native or custom elements) that each bridge the "State" to one external protocol, such as fetch, form, history, WebAuthn, user gestures. They write only their own attributes.
"State" is simply the live DOM.
Two demos to take a look at; both have zero lines of app JS and no build process:
- The Todo demo on Nucleus' landing page is a fully RESTful app in about 30 lines of HTML, 20 lines of Quark.
- The Wrenfield PWA demo is a fictional, full-featured ecommerce site with polished features like SSG, SPA, hydration, web AR/3d models, WebAuthn, View Transitions, touch gestures. Try it on mobile to get a native-like experience. https://wrenfield.excom.dev
The Nucleus site itself is also dogfooding the stack. Opening up your inspector will show a highly declarative document, which is the live State of the app. Other examples are in the sidebar. The Nucleus stack is currently being used in production by a few companies. Open source versions of their apps are coming soon, as demos.
The stack differs from things you're probably aware of:
- HTMX - server owns logic and swaps fragments. Quark owns orchestration on the client, with the document as the only state.
- Lit and other web component frameworks - Custom elements are also part of this stack, and there can potentially be interop. But the ASO architecture advises elements to never render their own opinionated children or business logic. That is left to you.
- Datastar / Alpine - JS expressions or signals inside attrs. Quark lives in a separate, decoupled sheet and has no expressions with side effects. It does not call anything except your named pure functions.
- Blackboard pattern - architecturally, this is the closest relative. The site has an "Advanced -> Prior Art" page which discusses this.
The Nucleus stack is in beta. Here are the edges:
- Quark: unlike CSS, rules will not revert when they stop matching. You need to write the inverse, if needed. This is by design. Regardless, I'm currently exploring the architectural feasibility of rule reversion.
- Quark: certain pseudoclasses like :focus, :checked, :invalid are not observed.
- Quark and the elements rely on some fairly new browser APIs (like the Command API, Baseline 2025). Polyfills will be included in the first stable release.
- Will not play with React and certain other frameworks that lock the DOM to their own internal state. You will need a Shadow DOM as a boundary between them and the Nucleus stack.
Depending on the bundle/loading strategy you choose, the whole stack is somewhere between 1kb and a maximum of 70kb (brotli). This includes all out-of-the-box elements that provide generic functionalities like data fetching, lazy loading, and UI things like drawers, tabs, etc.
I am very keen on hearing feedback on this project. Particularly on the ASO architecture and the Quark language.
Nucleus will remain in beta for a few more weeks, as features are optimized and feedback is incorporated.
Docs: https://nucleus.excom.dev
Repo: https://github.com/excom-dev/nucleus
Architecture: https://nucleus.excom.dev/docs/adapter_state_orchestrator