veloxc

The Velox CLI and dev server: scaffold, lint, build, run and watch .vx apps.

Overview

veloxc is the tooling front of the Velox workspace: a single binary that scaffolds new projects, lints .vx files, compiles single-file components to Rust (via velox-sfc), resolves CSS (via velox-style), links compiled apps (via velox-renderer), and runs a watch-and-rebuild dev server with an HMR control channel. Scaffolds wire your Cargo.toml to the six published workspace crates, and every command is veloxc <subcommand> — veloxc --help lists them, and veloxc <subcommand> --help is the authoritative flag reference.

Features

veloxc init — scaffolds a working todo app: Cargo.toml wired to Velox, a build.rs that compiles .vx files, assets, and a component tree
veloxc dev — watch-and-rebuild dev server: inotify-driven (no polling), debounced, with an HMR control channel on 127.0.0.1:31313
veloxc build — project build, or compile one .vx file — and every component it imports — to Rust for inspection
veloxc lint — parse errors, reactive-idiom advisories in <script>, and every CSS property that parses but paints nothing; --fix repairs trailing whitespace and missing final newlines
veloxc add component — PascalCase component scaffolds with named slots
Dependency wiring — scaffolds use relative path deps when built from a clone (or --local <path>), crates.io git pins otherwise

Installation

Requires Rust 1.85+ and Git.

cargo install veloxc

This installs the veloxc binary and pulls the three Velox crates it drives from crates.io: velox-sfc (.vx parsing and template code generation), velox-style (CSS), and velox-renderer (painting, events, HMR).

cargo add veloxc instead adds it as a build dependency — that is how scaffolded projects use it: their build.rs calls veloxc::build_cmd on src/App.vx on every cargo build (emitting cargo:rerun-if-changed for each .vx it reads), and src/main.rs include!s the generated module.

Working from a checkout:

git clone https://github.com/fahimaloy/velox.git
cd velox
cargo install --path veloxc --force

Quick start

# 1. Scaffold
veloxc init my-app
cd my-app

# 2. Watch, build, run — reload with `r`, quit with `q`
veloxc dev

# 3. One-shot commands
veloxc lint src/            # check every .vx file
veloxc run                  # build + run once
veloxc build --release      # optimized build

veloxc dev starts the dev server:

[velox] HMR dev server listening on 127.0.0.1:31313
  ⚡ Velox dev server v0.1.1
  ➤ Project: my-app
  ➤ Watching: ./src
  ➤ Watching: ./assets
  ➤ HMR: port 31313 (auto-reload on save)
  ➤ Build: debug
    r: reload   c: clear   q: quit

⏳ Compiling...

It builds the project, runs the app, and rebuilds on every save. This is a watch-and-rebuild loop: each change is a full cargo build followed by an app restart, so in-process state does not survive a save. Treat rebuild time as the cost of every edit.

Documentation

API reference: docs.rs/veloxc
Book: CLI reference — every subcommand and flag
Full CLI reference in the repository README: README.md

Workspace crates

Velox is a workspace of six published crates. This crate is marked (this crate).

Crate	What it provides	Documentation
velox-core	Reactive primitives: signals, effects, lifecycle hooks	docs.rs
velox-dom	`VNode` types, block + flex layout, positioning, overflow	docs.rs
velox-style	CSS parsing, selectors, cascade; styles applied to `VNode`	docs.rs
velox-renderer	Rendering backends, event dispatch, hit testing	docs.rs
velox-sfc	Single-file component compiler (pest grammar) → Rust	docs.rs
veloxc · this crate	The CLI and dev server	docs.rs

Status

Published on crates.io at 0.1.1.

All seven subcommands work: init, build, run, dev, lint, add component, version. Known limitations, stated plainly:

veloxc dev is a watch-and-rebuild loop, not hot reload. Module-level HotReload exists in the HMR protocol but is not implemented — every save is a full rebuild followed by an app restart. The HMR port is fixed at 31313 (there is no port flag).
The crates.io scaffold's git pin falls back to rev = "unknown" and Cargo fails with revspec 'unknown' not found. Until the fallback is fixed, scaffold from a clone (git clone https://github.com/fahimaloy/velox && cargo install --path veloxc), pass --local <path>, or drop the git = … / rev = … keys from every velox-* line in the generated Cargo.toml.
veloxc's dev-dependencies never reach a scaffolded app. They exist so integration tests can drive the real layout pass and run the pixel-level scoping proof in the default cargo test pass; the scaffolded Cargo.toml is generated independently and lists only the runtime crates.
veloxc version prints a hardcoded Edition: 2021 informational line (veloxc/src/bin/main.rs:196) — the workspace itself builds with edition 2024.

License

Licensed under MIT OR Apache-2.0.

veloxc 0.1.2