Roadmap#

• Completed
• TODO
  • Parking Lot

Completed#

NOTE: data-x-* is now data-volt-*

Foundations#

Goal: Establish project structure, tooling, and base reactivity primitives. Outcome: A bootable TypeScript project with working reactivity primitives and test coverage. Summary: A TypeScript project scaffold with implemented signal() (subscribe/set/get) and foundational reactivity tests establishes the base system.

Reactivity & Bindings#

Goal: Connect signals to DOM via declarative data-x-* bindings. Outcome: Reactive text/attribute binding with signals → DOM synchronization. Summary: Reactive DOM bindings (data-x-text, data-x-html, data-x-class) with a safe expression evaluator, mutation batching, and DOM testing ensure synchronized updates between signals and UI.

Actions & Effects#

Goal: Add event-driven behavior and derived reactivity. Outcome: Fully functional reactive UI layer with event bindings and computed updates. Summary: An event binding system with $el, $event, and derived signals (computed, effect, async effects) delivers a complete reactive event-driven UI layer.

Plugins Framework#

Goal: Build a modular plugin architecture with dynamic registration. Outcome: Stable plugin API enabling community-driven extensions. Summary: A modular plugin API with lifecycle hooks and built-in extensions (persist, scroll, url) enables dynamic feature registration and community contributions.

Backend Integration & HTTP Actions#

Goal: Provide backend integration with declarative HTTP requests and responses. Outcome: VoltX.js can make backend requests and update the DOM Summary: Declarative HTTP directives (data-volt-get|post|put|patch|delete) with swap strategies, loading indicators, error handling, and form serialization integrate VoltX.js seamlessly with backend APIs.

Markup Based Reactivity#

Goal: Allow Volt apps to declare state, bindings, and behavior entirely in HTML markup Outcome: Authors can ship examples without companion JavaScript bundles Summary: Declarative HTML state, binding, control-flow, and event directives with SSR support and a sandboxed evaluator enable Volt apps to run without separate JavaScript bundles.

Proxy-Based Reactivity Enhancements#

Goal: Use JavaScript Proxies to improve reactivity ergonomics and automatic dependency tracking. Outcome: More intuitive API with automatic dependency tracking and optional deep reactivity for objects/arrays. Summary: Proxy-driven automatic dependency tracking, deep reactive() objects, reactive arrays, lazy signal creation, and debugging utilities improve reactivity ergonomics and performance.

Reactive Attributes & Event Modifiers#

Goal: Extend VoltX.js with expressive attribute patterns and event options for fine-grained control. Outcome: VoltX.js supports rich declarative behaviors and event semantics built entirely on standard DOM APIs. Summary: Introduced expressive attribute patterns and event modifiers for precise DOM and input control, for fine-grained declarative behavior entirely through standard DOM APIs.

Global State#

Goal: Implement store/context pattern Outcome: VoltX.js provides intuitive global state management Summary: The scope injects helpers like $origin, $scope, $pulse, $store, $uid, $probe, $pins, and $arc, giving templates access to global state, microtask scheduling, deterministic IDs, element refs, and custom event dispatch without leaving declarative markup.

Animation & Transitions#

Goal: Add animation primitives for smooth UI transitions with Alpine/Datastar parity. Outcome: VoltX.js enables declarative animations and view transitions alongside reactivity. Summary: The surge directive ships fade/slide/scale/blur presets with duration and delay overrides, per-phase enter/leave control, and easing helpers, while the shift plugin applies reusable keyframe animations—both composable with data-volt-if/data-volt-show as showcased in the animations demo.

Navigation & History API Routing#

Goal: Provide seamless client-side navigation with a first-class History API router. Outcome: VoltX.js delivers accessible, stateful navigation with clean URLs and signal-driven routing. Summary: Added seamless client-side navigation through a History API–powered router, enabling declarative routing with data-volt-navigate and data-volt-url, reactive URL synchronization, smooth transitions, scroll and focus restoration, dynamic route parsing, and full integration with signals and the View Transition API for accessible, stateful navigation and clean URLs.

To-Do#

Focus: Versions v0.5.5 through v0.9.x prioritize core framework capabilities and performance:

• Bundle size reduction to <15KB gzipped (currently 19KB)
• CSP compatibility (removing Function constructor dependency)
• DOM morphing and SSE streaming support
• Optional scope inheritance for improved ergonomics

These milestones strengthen VoltX.js as a signals-based reactive framework with declarative-first design.

Error Handling & Diagnostics#

Goal: Provide clear, actionable feedback when runtime or directive errors occur. Outcome: VoltX.js surfaces developer-friendly diagnostics for expression evaluation, directive parsing, and network operations, making it easier to debug apps without opaque stack traces. Deliverables: - ✓ v0.5.1: Centralized error boundary system for directives and effects - ✓ v0.5.1: Sandbox error wrapping with contextual hints (directive name, expression, element) - ✓ v0.5.1: $volt.report(error, context) API for plugin and app-level reporting - ✓ v0.6.0: Enhanced console error messages with directive context - ✓ v0.6.0: Differentiated error levels: warn, error, fatal - ✓ v0.6.0: Documentation: "Understanding VoltX Errors" guide - v0.6.0: Add error handling examples to demo - v0.13.0: Visual in-DOM error overlays for development mode - v0.13.0: Runtime health monitor tracking failures - v0.13.0: Configurable global error policy

Persistence & Offline#

Goal: Introduce persistent storage and offline-first behaviors. Outcome: Resilient state persistence and offline replay built into VoltX.js. Deliverables: - ✓ Persistent signals (localStorage, sessionStorage, indexedDb) - ✓ Storage plugin (data-volt-persist) - v0.12.0: Storage modifiers on signals (.local, .session, .ifmissing) - v0.12.0: Sync strategy API (merge, overwrite, patch) for conflict resolution - v0.12.0: Cache invalidation strategies - v0.12.0: Offline queue for deferred stream events and HTTP requests - v0.12.0: Service Worker integration for offline-first apps - v0.12.0: Background sync for deferred requests - v0.12.0: Cross-tab synchronization via BroadcastChannel

Bundle Size Optimization#

Goal: Reduce bundle size to <15KB gzipped while maintaining full feature set. Outcome: Lightweight runtime footprint with comprehensive declarative capabilities. Deliverables: - v0.6.0: Audit and tree-shake unused code paths - v0.6.0: Optimize evaluator and binder implementations - v0.6.0: Minimize plugin footprint, ensure lazy loading - v0.6.0: Refactor expression compiler for smaller output - v0.6.0: Compress constant strings and reduce runtime helpers - v0.6.0: Optimize signal subscription management - v0.6.0: Production mode stripping (remove dev-only error messages) - v0.6.0: Aggressive minification pipeline tuning - v0.6.0: Target: <15KB gzipped sustained

IIFE Build Support#

Goal: Provide an IIFE build target for VoltX.js to support direct <script> tag usage without module systems. Outcome: VoltX.js can be used via CDN without build tools or module bundlers. Deliverables: - v0.6.0: IIFE build output (voltx.iife.js) alongside ESM build - v0.6.0: Global Volt namespace for browser environments - v0.6.0: CDN-friendly distribution (unpkg, jsdelivr) - v0.6.0: Update build pipeline to generate IIFE bundle - v0.6.0: Document usage: <script src="voltx.iife.min.js"></script> - v0.6.0: Ensure plugins work with IIFE build - v0.6.0: Add IIFE examples to documentation

Testing & Benchmarking#

Goal: Establish comprehensive testing infrastructure and performance benchmarking. Outcome: VoltX.js has rigorous end-to-end testing and quantifiable performance metrics against competing frameworks. Deliverables: - v0.7.0: Playwright-based integration test suite for real browser testing - v0.7.0: End-to-end tests for all core directives and plugins - v0.7.0: Cross-browser compatibility tests (Chrome, Firefox, Safari) - v0.7.0: Memory usage and leak detection benchmarks - v0.7.0: Bundle size tracking and regression detection - v0.7.0: Reactivity performance benchmarks (signal updates, computed chains, effect execution) - v0.7.0: DOM update performance benchmarks - v0.7.0: CI integration for automated benchmark runs and regression alerts

CSP Compatibility#

Goal: Make VoltX.js Content Security Policy compliant without 'unsafe-eval'. Outcome: VoltX.js can run in strict CSP environments (no Function constructor). Deliverables: - v0.7.0: Research and design CSP-safe evaluator architecture - v0.7.0: Evaluate trade-offs: AST interpreter vs limited expression subset - v0.7.0: Implement CSP-safe expression evaluator (AST-based or restricted syntax) - v0.7.0: Maintain expression feature parity where possible - v0.7.0: Fallback mode detection for environments requiring CSP - v0.7.0: Full test coverage for CSP mode - v0.7.0: Documentation on CSP limitations and alternatives - v0.7.0: Bundle split: standard build vs CSP build

DOM Morphing & Streaming#

Goal: Add intelligent DOM morphing and Server-Sent Events for real-time updates. Outcome: Built-in morphing and SSE streaming for seamless server-driven UI updates. Deliverables: - v0.8.0: Integrate Idiomorph or implement lightweight morphing algorithm - v0.8.0: data-volt-morph attribute for morphing-based swaps - v0.8.0: Preserve focus, scroll, and input state during morphs - v0.8.0: Server-Sent Events (SSE) integration - v0.8.0: data-volt-stream attribute for SSE endpoints - v0.8.0: Automatic reconnection with exponential backoff - v0.8.0: Signal patching from backend SSE events - v0.8.0: JSON Patch support for partial updates - v0.8.0: data-volt-ignore-morph for selective exclusion - v0.8.0: WebSocket as alternative to SSE - v0.8.0: Unified streaming API across SSE/WebSocket

Scope Inheritance & State Management#

Goal: Improve data scoping with optional inheritance for ergonomic nested components. Outcome: Flexible scoping patterns for complex component hierarchies. Deliverables: - v0.9.0: Optional scope inheritance via data-volt-scope="inherit" - v0.9.0: Child scopes inherit parent signals with override capability - v0.9.0: $parent accessor for explicit parent scope access - v0.9.0: Scoped context providers for dependency injection - v0.9.0: Enhanced $store with namespacing and modules - v0.9.0: Cross-scope signal sharing patterns

Background Requests & Reactive Polling#

Goal: Enable declarative background data fetching and periodic updates. Outcome: VoltX.js elements can fetch or refresh data automatically based on time, visibility, or reactive conditions. Deliverables: - v0.10.0: data-volt-visible for fetching when element enters viewport (IntersectionObserver) - v0.10.0: data-volt-poll attribute for periodic background requests - v0.10.0: Configurable intervals, delays, and signal-based triggers - v0.10.0: Automatic cancellation when elements unmount - v0.10.0: Conditional polling tied to reactive signals - v0.10.0: Background task scheduler with priority management

Attribute Prefix Support#

Goal: Support multiple attribute prefix options for developer preference. Outcome: VoltX.js supports voltx-, vx-, and data-volt- prefixes. Deliverables: - v0.11.0: Add support for voltx-* and vx-* attribute prefixes - v0.11.0: Recommend vx-* as primary in documentation - v0.11.0: Maintain backward compatibility with data-volt-* - v0.11.0: Update demo to use recommended prefix

Inspector & Developer Tools#

Goal: Improve developer experience and runtime introspection. Outcome: First-class developer ergonomics; VoltX.js is enjoyable to debug and extend. Deliverables: - v0.13.0: Visual in-DOM error overlays for development mode - v0.13.0: Runtime health monitor tracking failures - v0.13.0: Configurable global error policy (silent, overlay, throw) - v0.13.0: Developer overlay for inspecting signals, subscriptions, and effects - v0.13.0: Time-travel debugging for signal history - v0.13.0: Signal dependency graph visualization - v0.13.0: Performance profiling tools - v0.13.0: Browser console integration (window.$volt.inspect()) - v0.13.0: Dev logging toggle (Volt.debug = true) - v0.13.0: Request/response debugging (HTTP actions, SSE streams) - v0.13.0: Browser DevTools extension with full integration

Stable Release#

Goal: Prepare & ship the stable release Outcome: VoltX.js 1.0 is stable, documented, performant, and ready for production. Deliverables: - ✓ Documentation site (VitePress) - Full API reference with examples - Create generator in @voltx/cli package - Finalized plugin registry and CLI (volt plugins list/init) - Versioned documentation (https://stormlightlabs.github.io/volt) - Announcement post and release notes - Community contribution guide & governance doc

Parking Lot#

Evaluator & Binder Hardening#

All expression evaluation now flows through a cached new Function compiler guarded by a hardened scope proxy, with the binder slimmed into a directive registry so plugins self-register while tests verify the sandboxed error surfaces.