CLI#

⚠️ This CLI is unreleased as of writing. The documentation may change before the CLI is published in v0.6.0.

The VoltX.js CLI provides tools for creating and managing VoltX.js applications. Use it to scaffold new projects, run development servers, build for production, and download framework assets.

Installation#

The CLI is available as create-voltx on npm:

# Use with pnpm
pnpm create voltx my-app

# Use with npm
npm create voltx@latest my-app

# Use with npx
npx create-voltx my-app

For ongoing development commands, install the CLI in your project:

pnpm add -D create-voltx

Commands#

init#

Create a new VoltX.js project with an interactive template selector.

# Interactive mode - prompts for project name and template
pnpm create voltx

# Specify project name
pnpm create voltx my-app

# Using the voltx command
voltx init my-app

Templates:

• Minimal - Basic VoltX.js app with a counter demo
• With Router - Multi-page app with client-side routing
• With Plugins - Demonstration of all VoltX.js plugins
• Styles Only - HTML + CSS using VoltX.js styles without the framework

The init command:

• Creates project directory
• Generates HTML, CSS, package.json, and README
• Downloads latest VoltX.js assets from CDN
• Sets up development scripts

Generated Structure:

my-app/
├── index.html       # Main HTML file
├── styles.css       # Custom styles
├── package.json     # Project configuration
├── README.md        # Getting started guide
├── voltx.min.js     # VoltX.js framework
└── voltx.min.css    # VoltX.js base styles

dev#

Start a Vite development server for your VoltX.js project.

voltx dev

Options:

• -p, --port <port> - Port to run the dev server on (default: 3000)
• -o, --open - Open browser automatically

Examples:

# Start dev server on default port (3000)
voltx dev

# Use custom port
voltx dev --port 8080

# Open browser automatically
voltx dev --open

The dev server provides:

• Hot module replacement (HMR)
• Fast refresh for development
• Automatic browser reload
• HTTPS support (via Vite)

build#

Build your VoltX.js project for production.

voltx build

Options:

• --out <dir> - Output directory (default: dist)

Examples:

# Build to default dist/ directory
voltx build

# Build to custom directory
voltx build --out public

The build command:

• Minifies HTML, CSS, and JavaScript
• Optimizes assets for production
• Generates source maps
• Creates optimized bundle

download#

Download VoltX.js assets (JS and CSS) from the CDN.

voltx download

Options:

• --version <version> - VoltX.js version to download (default: latest)
• --no-js - Skip downloading JavaScript file
• --no-css - Skip downloading CSS file
• -o, --output <dir> - Output directory (default: current directory)

Examples:

# Download latest JS and CSS
voltx download

# Download specific version
voltx download --version 0.5.0

# Download only CSS
voltx download --no-js

# Download to custom directory
voltx download --output assets

This command downloads minified assets from the jsDelivr CDN.

Workflows#

Creating a New Project#

# Create new project
pnpm create voltx my-app

# Navigate to project
cd my-app

# Install dependencies
pnpm install

# Start dev server
pnpm dev

Development#

# Start dev server (watches for changes)
pnpm dev

# In another terminal, run tests if available
pnpm test

Production Build#

# Build for production
pnpm build

# Preview production build locally
npx vite preview --outDir dist

Updating VoltX.js Assets#

# Download latest version
voltx download

# Or download specific version
voltx download --version 0.5.1

Project Scripts#

All generated projects include these npm scripts:

{
  "scripts": {
    "dev": "voltx dev",
    "build": "voltx build"
  }
}

Run them with your package manager:

pnpm dev
pnpm build

Templates#

Minimal#

A basic VoltX.js application demonstrating:

• Declarative state with data-volt-state
• Reactive bindings
• Event handlers
• Counter example

With Router#

A multi-page application featuring:

• Client-side routing with History API
• Multiple routes (home, about, contact, 404)
• Navigation with data-volt-navigate
• Route matching with data-volt-url

With Plugins#

A comprehensive demo showcasing:

• Persist plugin (localStorage sync)
• Scroll plugin (smooth scrolling)
• URL plugin (URL parameter sync)
• Surge plugin (animations)
• Navigate plugin (routing)

Best for: Learning all VoltX.js features, reference implementation.

Styles Only#

HTML and CSS using VoltX.js styles without the reactive framework:

• VoltX.js CSS utilities
• Semantic HTML
• No JavaScript required

Configuration#

Vite Configuration#

The CLI uses Vite as the dev server and build tool. To customize Vite, create a vite.config.js in your project root:

import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    port: 3000,
  },
  build: {
    outDir: 'dist',
  },
});

See the Vite documentation for all available options.