a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
hypermedia
frontend
signals
build: setup release pipeline
+368
-47
+18
.github/workflows/publish.yml
+18
.github/workflows/publish.yml
···
1
+
# .github/workflows/publish.yml
2
+
3
+
name: Publish
4
+
5
+
on:
6
+
push:
7
+
branches:
8
+
- main
9
+
10
+
jobs:
11
+
publish:
12
+
runs-on: ubuntu-latest
13
+
permissions:
14
+
contents: read
15
+
id-token: write # The OIDC ID token is used for authentication with JSR.
16
+
steps:
17
+
- uses: actions/checkout@v4
18
+
- run: npx jsr publish
+141
RELEASE.md
+141
RELEASE.md
···
1
+
# Release Guide
2
+
3
+
This guide covers the process for publishing Volt.js packages to npm and JSR.
4
+
5
+
## Prerequisites
6
+
7
+
### npm
8
+
9
+
Ensure you have npm publishing rights:
10
+
11
+
```bash
12
+
npm whoami
13
+
```
14
+
15
+
Make sure you're logged in:
16
+
17
+
```bash
18
+
npm login
19
+
```
20
+
21
+
### JSR
22
+
23
+
No setup required. JSR authentication happens via browser during first publish.
24
+
25
+
## Pre-Release Checklist
26
+
27
+
1. Ensure all tests pass
28
+
29
+
```bash
30
+
pnpm test:run
31
+
```
32
+
33
+
2. Type check all packages
34
+
35
+
```bash
36
+
pnpm typecheck
37
+
```
38
+
39
+
3. Build all packages
40
+
41
+
```bash
42
+
pnpm build
43
+
```
44
+
45
+
4. Review changelog and update version numbers
46
+
47
+
## Publishing voltx.js
48
+
49
+
The core package is published as:
50
+
51
+
- **npm**: `voltx.js` (unscoped)
52
+
- **JSR**: `@voltx.js/core` (scoped, JSR requires scopes)
53
+
54
+
### 1. Update Version
55
+
56
+
Update version in both files:
57
+
58
+
- `lib/package.json`
59
+
- `lib/jsr.json`
60
+
61
+
Use semantic versioning (semver):
62
+
63
+
- Patch: bug fixes (0.1.0 → 0.1.1)
64
+
- Minor: new features, backward compatible (0.1.0 → 0.2.0)
65
+
- Major: breaking changes (0.1.0 → 1.0.0)
66
+
67
+
### 2. Build Package
68
+
69
+
```bash
70
+
cd lib
71
+
pnpm build
72
+
```
73
+
74
+
Verify build outputs:
75
+
76
+
- `dist/volt.js` - Main framework bundle
77
+
- `dist/volt.css` - CSS framework
78
+
- `dist/index.d.ts` - TypeScript declarations
79
+
80
+
### 3. Publish to npm
81
+
82
+
```bash
83
+
cd lib
84
+
npm publish --provenance
85
+
```
86
+
87
+
The `--provenance` flag adds supply chain security metadata when publishing from GitHub Actions.
88
+
89
+
### 4. Publish to JSR
90
+
91
+
```bash
92
+
cd lib
93
+
npx jsr publish
94
+
```
95
+
96
+
First time: Browser window opens for authentication
97
+
Subsequent publishes: Uses cached credentials
98
+
99
+
### 5. Verify Publication
100
+
101
+
npm:
102
+
103
+
```bash
104
+
npm view voltx.js
105
+
```
106
+
107
+
JSR:
108
+
109
+
```bash
110
+
npx jsr info @voltx.js/core
111
+
```
112
+
113
+
Or visit:
114
+
115
+
- npm: <https://www.npmjs.com/package/voltx.js>
116
+
- JSR: <https://jsr.io/@voltx.js/core>
117
+
118
+
## Post-Release
119
+
120
+
1. Create Git tag
121
+
122
+
```bash
123
+
git tag v0.1.0
124
+
git push origin v0.1.0
125
+
```
126
+
127
+
2. Create GitHub release with changelog
128
+
129
+
3. Update documentation if needed
130
+
131
+
## To-Do
132
+
133
+
Consider setting up GitHub Actions workflow to automate:
134
+
135
+
- Publishing to npm
136
+
- Version bumping
137
+
- Building
138
+
- Git tagging
139
+
- GitHub release creation
140
+
141
+
Consider using `bumpp` or `changeset` for automated version management across the monorepo.
+2
dev/package.json
+2
dev/package.json
···
3
3
"version": "0.1.0",
4
4
"description": "Local development CLI for Volt.js",
5
5
"type": "module",
6
+
"author": "Owais Jamil",
6
7
"license": "MIT",
8
+
"repository": { "type": "git", "url": "https://github.com/stormlightlabs/volt.git", "directory": "dev" },
7
9
"bin": { "volt": "./dist/index.js" },
8
10
"files": ["dist"],
9
11
"main": "./dist/index.js",
+6
-6
docs/internals/debugging.md
+6
-6
docs/internals/debugging.md
···
1
1
# Debugging
2
2
3
-
The Volt.js debugging system provides introspection and visualization tools for reactive primitives.
4
-
It's a lazy-loadable module (`volt/debug`) that doesn't affect production bundle size.
3
+
The VoltX.js debugging system provides introspection and visualization tools for reactive primitives.
4
+
It's a lazy-loadable module (`voltx.js/debug`) that doesn't affect production bundle size.
5
5
6
6
## Architecture
7
7
···
101
101
For development, import debug utilities directly:
102
102
103
103
```ts
104
-
import { debugSignal, debugComputed, logAllSignals, buildDependencyGraph } from 'volt/debug';
104
+
import { debugSignal, debugComputed, logAllSignals, buildDependencyGraph } from 'voltx.js/debug';
105
105
```
106
106
107
107
For debugging existing code, attach debugger to existing signals:
108
108
109
109
```ts
110
-
import { signal } from 'volt';
111
-
import { attachDebugger, vdebugger } from 'volt/debug';
110
+
import { signal } from 'voltx.js';
111
+
import { attachDebugger, vdebugger } from 'voltx.js/debug';
112
112
113
113
const count = signal(0);
114
114
attachDebugger(count, 'signal', 'count');
···
118
118
For browser console debugging, expose vdebugger globally:
119
119
120
120
```ts
121
-
import { vdebugger } from 'volt/debug';
121
+
import { vdebugger } from 'voltx.js/debug';
122
122
window.vdebugger = vdebugger;
123
123
```
124
124
+2
-2
docs/spec/plugin-spec.md
+2
-2
docs/spec/plugin-spec.md
···
1
-
# Volt Plugin System Spec
1
+
# VoltX Plugin System Spec
2
2
3
3
## Overview
4
4
···
67
67
### Example: Custom Tooltip Plugin
68
68
69
69
```ts
70
-
import { registerPlugin } from 'volt';
70
+
import { registerPlugin } from 'voltx.js';
71
71
72
72
registerPlugin('tooltip', (context, value) => {
73
73
const tooltip = document.createElement('div');
+32
lib/.npmignore
+32
lib/.npmignore
···
1
+
# Development files
2
+
*.log
3
+
*.swp
4
+
*.swo
5
+
*~
6
+
7
+
# Test files
8
+
test/
9
+
**/*.test.ts
10
+
**/*.spec.ts
11
+
coverage/
12
+
13
+
# Build config
14
+
tsconfig*.json
15
+
vite.config.ts
16
+
vitest.config.ts
17
+
postcss.config.js
18
+
eslint.config.js
19
+
20
+
# Development
21
+
node_modules/
22
+
.DS_Store
23
+
.vscode/
24
+
.idea/
25
+
26
+
# Demo
27
+
demo/
28
+
index.html
29
+
30
+
# Keep dist and src
31
+
!dist/
32
+
!src/
+21
lib/LICENSE
+21
lib/LICENSE
···
1
+
MIT License
2
+
3
+
Copyright (c) 2025 [Owais J]
4
+
5
+
Permission is hereby granted, free of charge, to any person obtaining a copy
6
+
of this software and associated documentation files (the "Software"), to deal
7
+
in the Software without restriction, including without limitation the rights
8
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+
copies of the Software, and to permit persons to whom the Software is
10
+
furnished to do so, subject to the following conditions:
11
+
12
+
The above copyright notice and this permission notice shall be included in all
13
+
copies or substantial portions of the Software.
14
+
15
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+
SOFTWARE.
+68
lib/README.md
+68
lib/README.md
···
1
+
# VoltX.js
2
+
3
+
A lightweight reactive framework for declarative UIs. Build interactive applications using only HTML attributes powered by signals.
4
+
5
+
## Features
6
+
7
+
- Declarative HTML-driven reactivity via `data-volt-*` attributes
8
+
- Signal-based state management with automatic DOM updates
9
+
- Zero dependencies, under 15 KB gzipped
10
+
- No virtual DOM, no build step required
11
+
- Server-side rendering and hydration support
12
+
- Built-in plugins for persistence, routing, and scroll management
13
+
14
+
## Installation
15
+
16
+
### npm
17
+
18
+
```bash
19
+
npm install voltx.js
20
+
```
21
+
22
+
### JSR
23
+
24
+
```bash
25
+
npx jsr add @voltx/core
26
+
```
27
+
28
+
### Deno
29
+
30
+
```typescript
31
+
import { charge, signal } from "jsr:@voltx/core";
32
+
```
33
+
34
+
## Quick Start
35
+
36
+
```html
37
+
<div data-volt data-volt-state='{"count": 0}'>
38
+
<p data-volt-text="count"></p>
39
+
<button data-volt-on-click="count.set(count.get() + 1)">Increment</button>
40
+
</div>
41
+
42
+
<script type="module">
43
+
import { charge } from 'voltx.js';
44
+
charge();
45
+
</script>
46
+
```
47
+
48
+
## Using CSS
49
+
50
+
Import the optional CSS framework:
51
+
52
+
```typescript
53
+
import 'voltx.js/css';
54
+
```
55
+
56
+
Or include via CDN:
57
+
58
+
```html
59
+
<link rel="stylesheet" href="https://unpkg.com/voltx.js/dist/volt.css">
60
+
```
61
+
62
+
## Documentation
63
+
64
+
Full documentation available at [your-docs-url]
65
+
66
+
## License
67
+
68
+
MIT
+7
lib/jsr.json
+7
lib/jsr.json
+23
-4
lib/package.json
+23
-4
lib/package.json
···
1
1
{
2
-
"name": "volt",
3
-
"private": true,
2
+
"name": "voltx.js",
4
3
"version": "0.1.0",
4
+
"description": "A lightweight reactive framework for declarative UIs",
5
5
"type": "module",
6
+
"author": "Owais Jamil",
7
+
"license": "MIT",
8
+
"repository": { "type": "git", "url": "https://github.com/stormlightlabs/volt.git", "directory": "lib" },
9
+
"keywords": ["reactive", "signals", "framework", "ui", "declarative", "html", "dom", "frontend"],
10
+
"main": "./dist/volt.js",
11
+
"module": "./dist/volt.js",
12
+
"types": "./dist/index.d.ts",
13
+
"exports": {
14
+
".": { "types": "./dist/index.d.ts", "import": "./dist/volt.js" },
15
+
"./debug": { "types": "./dist/debug.d.ts", "import": "./dist/debug.js" },
16
+
"./css": "./dist/volt.css",
17
+
"./package.json": "./package.json"
18
+
},
19
+
"files": ["dist", "src", "README.md"],
6
20
"scripts": {
7
21
"dev": "vite",
8
22
"build": "pnpm build:lib && pnpm build:css",
9
-
"build:lib": "tsc && vite build --mode lib",
23
+
"build:lib": "tsc -p tsconfig.build.json && vite build --mode lib",
10
24
"build:css": "postcss src/styles/index.css -o dist/volt.css",
11
25
"build:css:min": "postcss src/styles/index.css -o dist/volt.min.css --env production",
12
26
"preview": "vite preview",
13
27
"test": "vitest",
14
28
"test:run": "vitest run",
15
-
"typecheck": "tsc --noEmit"
29
+
"typecheck": "tsc --noEmit",
30
+
"prepublishOnly": "pnpm build && pnpm test:run",
31
+
"publish:npm": "npm publish --access=public",
32
+
"publish:jsr": "npx jsr publish",
33
+
"publish:all": "pnpm publish:npm && pnpm publish:jsr"
16
34
},
35
+
"publishConfig": { "access": "public" },
17
36
"devDependencies": {
18
37
"@testing-library/dom": "^10.4.1",
19
38
"@testing-library/jest-dom": "^6.9.1",
+3
-3
lib/src/debug.ts
+3
-3
lib/src/debug.ts
···
2
2
* Volt.js Debug Utilities
3
3
*
4
4
* Lazy-loadable debugging module for signal introspection and visualization.
5
-
* Import from 'volt/debug' to access these utilities without affecting production bundle size.
5
+
* Import from 'voltx.js/debug' to access these utilities without affecting production bundle size.
6
6
*
7
7
* @example
8
8
* ```ts
9
-
* import { debugSignal, debugComputed, logAllSignals } from 'volt/debug';
9
+
* import { debugSignal, debugComputed, logAllSignals } from 'voltx.js/debug';
10
10
*
11
11
* const count = debugSignal(0, 'count');
12
12
* const doubled = debugComputed(() => count.get() * 2, 'doubled');
···
14
14
* logAllSignals();
15
15
* ```
16
16
*
17
-
* @module volt/debug
17
+
* @module voltx.js/debug
18
18
* @packageDocumentation
19
19
*/
20
20
+17
-19
lib/src/demo/index.ts
+17
-19
lib/src/demo/index.ts
···
20
20
registerPlugin("scroll", scrollPlugin);
21
21
registerPlugin("url", urlPlugin);
22
22
23
-
const message = signal("Welcome to Volt.js Demo");
23
+
const message = signal("Welcome to the Volt.js Demo");
24
24
const count = signal(0);
25
25
const doubled = computed(() => count.get() * 2);
26
26
···
172
172
scrollToSection,
173
173
};
174
174
175
-
/**
176
-
* Build the complete demo structure programmatically
177
-
*/
175
+
const buildNav = () =>
176
+
dom.nav(
177
+
null,
178
+
dom.a({ href: "#typography" }, "Typography"),
179
+
" | ",
180
+
dom.a({ href: "#interactivity" }, "Interactivity"),
181
+
" | ",
182
+
dom.a({ href: "#forms" }, "Forms"),
183
+
" | ",
184
+
dom.a({ href: "#reactivity" }, "Reactivity"),
185
+
" | ",
186
+
dom.a({ href: "#plugins" }, "Plugins"),
187
+
);
188
+
178
189
function buildDemoStructure(): HTMLElement {
179
-
const container = dom.div(
190
+
return dom.div(
180
191
null,
181
192
dom.header(
182
193
null,
···
188
199
null,
189
200
"This demo demonstrates both the framework's reactive capabilities and the elegant, semantic styling of Volt CSS. No CSS classes needed!",
190
201
),
191
-
),
192
-
dom.nav(
193
-
null,
194
-
dom.a({ href: "#typography" }, "Typography"),
195
-
" | ",
196
-
dom.a({ href: "#interactivity" }, "Interactivity"),
197
-
" | ",
198
-
dom.a({ href: "#forms" }, "Forms"),
199
-
" | ",
200
-
dom.a({ href: "#reactivity" }, "Reactivity"),
201
-
" | ",
202
-
dom.a({ href: "#plugins" }, "Plugins"),
202
+
buildNav(),
203
203
),
204
204
),
205
205
dom.el(
···
229
229
),
230
230
),
231
231
);
232
-
233
-
return container;
234
232
}
235
233
236
234
export function setupDemo() {
+3
-7
lib/src/demo/sections/interactivity.ts
+3
-7
lib/src/demo/sections/interactivity.ts
···
21
21
null,
22
22
"Modern browsers support the dialog element natively, providing built-in accessibility features and keyboard handling (ESC to close, focus trapping, etc.).",
23
23
),
24
-
" Volt CSS styles it elegantly, and Volt.js handles the interaction.",
24
+
" VoltX CSS styles it elegantly, and VoltX.js handles the interaction.",
25
25
),
26
26
dom.button({ "data-volt-on-click": "openDialog" }, "Open Dialog"),
27
27
dom.p({ "data-volt-if": "dialogMessage.get()", "data-volt-text": "dialogMessage" }),
···
32
32
dom.header(
33
33
null,
34
34
dom.h3(null, "Dialog Demo"),
35
-
dom.button({
36
-
"data-volt-on-click": "closeDialog",
37
-
"aria-label": "Close",
38
-
style: "float: right; background: none; border: none; font-size: 1.5rem; cursor: pointer;",
39
-
}, "×"),
35
+
dom.button({ "data-volt-on-click": "closeDialog", "aria-label": "Close" }, "×"),
40
36
),
41
37
dom.form(
42
38
{ "data-volt-on-submit": "submitDialog" },
···
48
44
required: true,
49
45
}),
50
46
dom.footer(
51
-
{ style: "display: flex; gap: 1rem; justify-content: flex-end;" },
47
+
null,
52
48
dom.button({ type: "button", "data-volt-on-click": "closeDialog" }, "Cancel"),
53
49
dom.button({ type: "submit" }, "Submit"),
54
50
),
+1
-1
lib/src/index.ts
+1
-1
lib/src/index.ts
+12
lib/tsconfig.build.json
+12
lib/tsconfig.build.json
+8
-1
lib/vite.config.ts
+8
-1
lib/vite.config.ts
···
34
34
},
35
35
build: mode === "lib"
36
36
? {
37
-
lib: { entry: path.resolve(__dirname, "src/index.ts"), name: "Volt", fileName: "volt", formats: ["es"] },
37
+
lib: {
38
+
entry: {
39
+
volt: path.resolve(__dirname, "src/index.ts"),
40
+
debug: path.resolve(__dirname, "src/debug.ts"),
41
+
},
42
+
name: "Volt",
43
+
formats: ["es"],
44
+
},
38
45
rolldownOptions: { output: { assetFileNames: "volt.[ext]" } },
39
46
}
40
47
: undefined,
+4
-4
package.json
+4
-4
package.json
···
1
1
{
2
-
"name": "volt-monorepo",
2
+
"name": "voltx.js-monorepo",
3
3
"version": "1.0.0",
4
4
"private": true,
5
5
"type": "module",
6
6
"scripts": {
7
-
"dev": "pnpm --filter volt dev",
7
+
"dev": "pnpm --filter voltx.js dev",
8
8
"build": "pnpm -r build",
9
-
"preview": "pnpm --filter volt preview",
9
+
"preview": "pnpm --filter voltx.js preview",
10
10
"test": "pnpm -r test",
11
-
"test:ui": "pnpm --filter volt test:ui",
11
+
"test:ui": "pnpm --filter voltx.js test:ui",
12
12
"test:run": "pnpm -r test:run",
13
13
"docs:dev": "pnpm --filter @volt/docs dev",
14
14
"docs:build": "pnpm --filter @volt/docs build",