desertthunder.dev / voltx
a reactive (signals based) hypermedia web framework (wip) stormlightlabs.github.io/volt/
hypermedia frontend signals
fork atom
voltx / docs / installation.md
at main 4.7 kB view raw view code

Installation#

VoltX.js can be installed via CDN or package manager. Choose the method that best fits your project setup.

CDN (unpkg)#

The 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.

ES Modules#

Use the module build for modern browsers with ES module support:

<script type="module">
  import { charge, registerPlugin } from 'https://unpkg.com/voltx.js@latest/dist/volt.js';
  charge();
</script>

You can optionally pin to a specific version:

<script type="module">
  import { charge } from 'https://unpkg.com/voltx.js@0.1.0/dist/volt.js';
  charge();
</script>

CLI (⚠️ Unreleased as of v0.5.0)#

The fastest way to create a new VoltX.js project is with the CLI:

pnpm create voltx my-app
cd my-app
pnpm install
pnpm dev

This scaffolds a complete project with development server, build tools, and framework assets. See the CLI Guide for all available commands and templates.

Package Manager#

For applications using node based tools, install VoltX.js via npm or JSR:

npm#

npm install voltx.js

pnpm add voltx.js

JSR (Deno, Node.js, Bun)#

npx jsr add @voltx/core

deno add jsr:@voltx/core

Module Imports#

Import only the functions you need to minimize bundle size:

// npm
import { charge, registerPlugin } from 'voltx.js';

// JSR
import { charge, registerPlugin } from '@voltx/core';

registerPlugin('persist', persistPlugin);
charge();

The framework uses tree-shaking to eliminate unused code when bundled with modern build tools like Vite, Rollup, or Webpack.

TypeScript#

VoltX.js is written in TypeScript and includes complete type definitions.

TypeScript users get automatic type inference for:

  • Signal values and methods
  • Computed dependencies
  • Plugin contexts
  • Scope objects passed to mount()

Basic Setup#

For applications that can be built entirely in HTML, use the declarative approach with charge():

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>VoltX.js App</title>
</head>
<body>
  <div data-volt data-volt-state='{"count": 0}'>
    <h1 data-volt-text="count">0</h1>
    <button data-volt-on-click="count.set(count.get() + 1)">Increment</button>
  </div>

  <script type="module">
    import { charge } from 'https://unpkg.com/voltx.js@latest/dist/volt.js';
    charge();
  </script>
</body>
</html>

The charge() function auto-discovers all elements with the data-volt attribute and mounts them with their declared state.

Programmatic Mode#

For applications requiring initialization logic, use the programmatic API with mount():

<script type="module">
  import { mount, signal } from 'https://unpkg.com/voltx.js@latest/dist/volt.js';

  const count = signal(0);

  mount(document.querySelector('#app'), {
    count,
    increment: () => count.set(count.get() + 1)
  });
</script>

This approach gives you full control over signal creation, initialization, and the scope object.

Server-Side Rendering#

For SSR applications, use the hydrate() function instead of charge() to preserve server-rendered HTML and attach interactivity:

<script type="module">
  import { hydrate } from 'voltx.js';
  // or: import { hydrate } from '@voltx/core';
  hydrate();
</script>

See the Server-Side Rendering guide for complete hydration patterns and lifecycle coordination tips.

Plugin Setup#

VoltX.js includes several built-in plugins that must be registered before use:

<script type="module">
  import { charge, registerPlugin, persistPlugin, scrollPlugin, urlPlugin } from 'voltx.js';

  registerPlugin('persist', persistPlugin);
  registerPlugin('scroll', scrollPlugin);
  registerPlugin('url', urlPlugin);

  charge();
</script>

Register plugins before calling charge(), mount(), or hydrate() to ensure they're available for binding resolution.

Browser Compatibility#

VoltX.js requires modern browsers with support for:

  • ES2020 syntax (optional chaining, nullish coalescing)
  • ES modules
  • Proxy objects
  • CSS custom properties

Minimum versions:

  • Chrome 90+
  • Firefox 88+
  • Safari 14+
  • Edge 90+

Next Up#