a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
desertthunder.dev
hypermedia
frontend
signals
1# Installation
2
3VoltX.js can be installed via CDN or package manager. Choose the method that best fits your project setup.
4
5## CDN (unpkg)
6
7The simplest way to get started is loading VoltX.js directly from a CDN. This approach requires no build tools and works immediately in any HTML file.
8
9### ES Modules
10
11Use the module build for modern browsers with ES module support:
12
13```html
14<script type="module">
15 import { charge, registerPlugin } from 'https://unpkg.com/voltx.js@latest/dist/volt.js';
16 charge();
17</script>
18```
19
20You can optionally pin to a specific version:
21
22```html
23<script type="module">
24 import { charge } from 'https://unpkg.com/voltx.js@0.1.0/dist/volt.js';
25 charge();
26</script>
27```
28
29## CLI (⚠️ Unreleased as of v0.5.0)
30
31The fastest way to create a new VoltX.js project is with the CLI:
32
33```bash
34pnpm create voltx my-app
35cd my-app
36pnpm install
37pnpm dev
38```
39
40This scaffolds a complete project with development server, build tools, and framework assets. See the [CLI Guide](./cli) for all available commands and templates.
41
42## Package Manager
43
44For applications using node based tools, install VoltX.js via npm or JSR:
45
46### npm
47
48```bash
49npm install voltx.js
50```
51
52```bash
53pnpm add voltx.js
54```
55
56### JSR (Deno, Node.js, Bun)
57
58```bash
59npx jsr add @voltx/core
60```
61
62```bash
63deno add jsr:@voltx/core
64```
65
66### Module Imports
67
68Import only the functions you need to minimize bundle size:
69
70```js
71// npm
72import { charge, registerPlugin } from 'voltx.js';
73
74// JSR
75import { charge, registerPlugin } from '@voltx/core';
76
77registerPlugin('persist', persistPlugin);
78charge();
79```
80
81The framework uses tree-shaking to eliminate unused code when bundled with modern build tools like Vite, Rollup, or Webpack.
82
83## TypeScript
84
85VoltX.js is written in TypeScript and includes complete type definitions.
86
87TypeScript users get automatic type inference for:
88
89- Signal values and methods
90- Computed dependencies
91- Plugin contexts
92- Scope objects passed to `mount()`
93
94## Basic Setup
95
96### Declarative Mode (Recommended)
97
98For applications that can be built entirely in HTML, use the declarative approach with `charge()`:
99
100```html
101<!DOCTYPE html>
102<html lang="en">
103<head>
104 <meta charset="UTF-8">
105 <meta name="viewport" content="width=device-width, initial-scale=1.0">
106 <title>VoltX.js App</title>
107</head>
108<body>
109 <div data-volt data-volt-state='{"count": 0}'>
110 <h1 data-volt-text="count">0</h1>
111 <button data-volt-on-click="count.set(count.get() + 1)">Increment</button>
112 </div>
113
114 <script type="module">
115 import { charge } from 'https://unpkg.com/voltx.js@latest/dist/volt.js';
116 charge();
117 </script>
118</body>
119</html>
120```
121
122The `charge()` function auto-discovers all elements with the `data-volt` attribute and mounts them with their declared state.
123
124### Programmatic Mode
125
126For applications requiring initialization logic, use the programmatic API with `mount()`:
127
128```html
129<script type="module">
130 import { mount, signal } from 'https://unpkg.com/voltx.js@latest/dist/volt.js';
131
132 const count = signal(0);
133
134 mount(document.querySelector('#app'), {
135 count,
136 increment: () => count.set(count.get() + 1)
137 });
138</script>
139```
140
141This approach gives you full control over signal creation, initialization, and the scope object.
142
143## Server-Side Rendering
144
145For SSR applications, use the `hydrate()` function instead of `charge()` to preserve server-rendered HTML and attach interactivity:
146
147```html
148<script type="module">
149 import { hydrate } from 'voltx.js';
150 // or: import { hydrate } from '@voltx/core';
151 hydrate();
152</script>
153```
154
155See the [Server-Side Rendering guide](./usage/ssr) for complete hydration patterns and lifecycle coordination tips.
156
157## Plugin Setup
158
159VoltX.js includes several built-in plugins that must be registered before use:
160
161```html
162<script type="module">
163 import { charge, registerPlugin, persistPlugin, scrollPlugin, urlPlugin } from 'voltx.js';
164
165 registerPlugin('persist', persistPlugin);
166 registerPlugin('scroll', scrollPlugin);
167 registerPlugin('url', urlPlugin);
168
169 charge();
170</script>
171```
172
173Register plugins before calling `charge()`, `mount()`, or `hydrate()` to ensure they're available for binding resolution.
174
175## Browser Compatibility
176
177VoltX.js requires modern browsers with support for:
178
179- ES2020 syntax (optional chaining, nullish coalescing)
180- ES modules
181- Proxy objects
182- CSS custom properties
183
184**Minimum versions:**
185
186- Chrome 90+
187- Firefox 88+
188- Safari 14+
189- Edge 90+
190
191## Next Up
192
193- Read the [Framework Overview](./overview) to understand core concepts
194- Learn about [State Management](./usage/state) with signals and computed values
195- Explore available [Bindings](./usage/bindings) for DOM manipulation
196- Check out [Expression Evaluation](./usage/expressions) for template syntax