a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
hypermedia
frontend
signals
docs: move framework details to docs/overview
+31
-46
+7
-46
README.md
+7
-46
README.md
···
11
11
12
12
Volt is a monorepo centered around the VoltX.js runtime—a lightweight, declarative alternative to component-centric UI frameworks. The repo also ships the Volt CLI and the documentation site that demonstrates and explains the runtime.
13
13
14
-
## Philosophy/Goals
15
-
16
-
- Behavior is declared via `data-volt-*` attributes.
17
-
- HTML drives the UI, not components.
18
-
- Core under **20 KB gzipped**, zero dependencies.
19
-
- Signals update the DOM directly without a virtual DOM.
20
-
- Native Server-Sent Events (SSE) and WebSocket patch updates.
21
-
- No reactivity scheduler, no VDOM diffing.
22
-
- Extend behavior declaratively (persist, scroll, animate, etc.).
23
-
- Progressive enhancement, i.e. works with static HTML out of the box.
14
+
## Local Development
24
15
25
-
### Values
26
-
27
-
- Never exceed 15 KB for the core runtime.
28
-
- No custom build systems — work with any backend.
29
-
- All source in TypeScript, no magical DSLs.
30
-
- Every feature ships with a test harness.
31
-
32
-
## Concepts
33
-
34
-
| Concept | Description |
35
-
| -------- | ------------------------------------------------------------------------------------------------- |
36
-
| Signals | Reactive primitives that automatically update DOM bindings when changed. |
37
-
| Bindings | `data-volt-text`, `data-volt-html`, `data-volt-class` connect attributes or text to expressions. |
38
-
| Actions | `data-volt-on-click`, `data-volt-on-input`, etc. attach event handlers declaratively. |
39
-
| Streams | `data-volt-stream="/events"` listens for SSE or WebSocket updates and applies JSON patches. |
40
-
| Plugins | Modular extensions (`data-volt-persist`, `data-volt-surge`, `data-volt-shift`, etc.) to enhance the core. |
41
-
42
-
## VoltX.css
43
-
44
-
VoltX ships with an optional classless CSS framework inspired by Pico CSS and Tufte CSS. It provides beautiful, semantic styling for HTML elements without requiring any CSS classes—just write semantic markup and it looks great out of the box.
45
-
46
-
Features include typography with modular scale, Tufte-style sidenotes, styled form elements, dialogs, accordions, tooltips, tables, and more. See the framework's [README](./lib/README.md#voltxcss) for installation and usage details.
47
-
48
-
Here are some highlights
49
-
50
-
51
-
52
-
53
-
54
-
55
-
56
-
## Packages
16
+
### Packages
57
17
58
18
```sh
59
19
volt/
60
20
├── lib/ VoltX.js runtime published to npm (`voltx.js`) and JSR (`@voltx/core`)
61
-
├── dev/ Volt CLI and local tooling
21
+
├── dev/ VoltX dev CLI and local tooling
22
+
├── cli/ Project scaffolding and management CLI (`create-voltx`)
62
23
└── docs/ VitePress documentation site
63
24
```
64
25
65
-
## Getting Started
26
+
### Getting Started
66
27
67
28
- Runtime usage: see [`lib/README.md`](./lib/README.md) for installation guides and quick-start examples.
68
29
- Local development: `pnpm install` then `pnpm --filter lib dev` run package-specific scripts (`build`, `test`, etc.).
69
30
- Review [contribution](./CONTRIBUTING.md) guidelines
70
-
- Documentation: `pnpm --filter docs docs:dev` launches the VitePress site.
31
+
- Documentation: `pnpm docs:dev` launches the VitePress site.
71
32
72
33
### Working on New Features
73
34
···
94
55
95
56
## License
96
57
97
-
MIT License © 2025 Stormlight Labs
58
+
[MIT License](./lib/LICENSE) © 2025 Stormlight Labs
+24
docs/overview.md
+24
docs/overview.md
···
41
41
- TypeScript source
42
42
- Every feature tested
43
43
44
+
## Concepts
45
+
46
+
| Concept | Description |
47
+
| -------- | --------------------------------------------------------------------------------------------------------- |
48
+
| Signals | Reactive primitives that automatically update DOM bindings when changed. |
49
+
| Bindings | `data-volt-text`, `data-volt-html`, `data-volt-class` connect attributes or text to expressions. |
50
+
| Actions | `data-volt-on-click`, `data-volt-on-input`, etc. attach event handlers declaratively. |
51
+
| Streams | `data-volt-stream="/events"` listens for SSE or WebSocket updates and applies JSON patches. |
52
+
| Plugins | Modular extensions (`data-volt-persist`, `data-volt-surge`, `data-volt-shift`, etc.) to enhance the core. |
53
+
54
+
## VoltX.css
55
+
56
+
VoltX ships with an optional classless CSS framework inspired by Pico CSS and Tufte CSS. It provides beautiful, semantic styling for HTML elements without requiring any CSS classes—just write semantic markup and it looks great out of the box.
57
+
58
+
Features include typography with modular scale, Tufte-style sidenotes, styled form elements, dialogs, accordions, tooltips, tables, and more. See the framework's [README](../lib/README.md#voltxcss) for installation and usage details.
59
+
60
+
Here are some highlights
61
+
62
+
63
+
64
+
65
+
66
+
67
+
44
68
## Browser Support
45
69
46
70
Modern browsers (Chrome 90+, Firefox 88+, Safari 14+) with support for: