One file describes one component
A .wisp file holds an optional Rust script, an optional CSS style section and an HTML template. The script and style appear before the template, in either order, at most once each. The template must contain something.
<script>let count: Signal<i32> = Signal::new(0);let increment = move || count.update(|n| *n += 1);</script><style>:global(body) { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; padding: 16px; }button { padding: 8px 12px; }</style><button onclick={increment}>Clicked {count} times</button> The file name determines the generated type. counter.wisp becomes Counter; text-input.wisp and text_input.wisp both become TextInput. Avoid names that would collide after this conversion.
The script runs at mount
Script statements run once, in order, when the component mounts. A typed signal or memo declaration becomes a public field on the generated component. A closure assigned to a local name can be used as an event handler.
| Declaration | Compiler treatment |
|---|---|
let count: Signal<i32> = Signal::new(0); | State field on the component |
let doubled: Memo<i32> = Memo::new(...); | Derived-state field |
#[prop] let label: String = "Count".into(); | Props field with a default |
#[prop] let children: Snippet = Snippet::empty(); | The content a parent writes inside this component’s tag |
#[dispatcher(pick)] let events; | A handle that raises the component’s own events, which a parent listens for with onpick |
let increment = move \|\| ...; | Handler available to the template |
Signals and memos need explicit types because those types appear in the generated struct. A prop needs a name, type and default. The compiler refuses declarations that cannot form those fields. A handler may return Result<(), E> with E: Display; the compiler refuses a handler that assigns to a captured binding.
Generated Rust remains readable
For each file the compiler writes a STYLE constant holding the style text, a SCOPE constant when the file has a style section, a props struct, a component struct and methods to mount or unmount it. mount and mount_before create the tree under an owner. roots() returns the component’s current top-level nodes. unmount disposes its owner and removes its nodes.
The generated code calls the Dom trait rather than browser DOM APIs. The Document in vapors-elements implements it over the element tree that is styled, laid out and drawn; RecordingDom in vapors-dom implements it for tests. Elements and events lists which elements and events the document supports.
Styles are scoped to the component
mount_before registers the component’s style with the Dom under its SCOPE, once however often the component is mounted, and gives each element the component creates a data-wisp attribute holding that scope. The document rewrites each selector in the style so it matches only elements carrying that attribute. A child component’s elements carry the child’s scope, so a parent’s rule does not reach them.
:global(...) leaves one compound unscoped, for an element the component did not create, such as :global(body). CSS and styling gives the specificity rules and the refused forms.
Include generated components in a crate
A build script calls vapors_compiler::build::compile_dir("src"). The compiler scans that directory and writes generated modules into Cargo’s output directory.
// build.rs
fn main() {
vapors_compiler::build::compile_dir("src");
} // src/lib.rs
include!(concat!(env!("OUT_DIR"), "/wisp.rs")); The crate needs vapors-dom and vapors-signals as dependencies and vapors-compiler as a build dependency. Drawing the components also needs vapors-elements, vapors-text, vapors-app and vapors-platform. The crates are not published, so these are path dependencies whose paths depend on where your checkout sits. The framework guide gives the layout.
compile_dir_global is the alternative for a crate whose application adds each component’s style as a global sheet: nothing is scoped and the generated code has no SCOPE.
Errors have source positions
Refusals use file:line:col: message. Unknown elements, malformed template blocks, repeated attributes, a data-wisp attribute (reserved for the scope) and unsupported forms fail rather than being ignored. An unsupported syntax form does not become a partially generated component. Rust type errors are checked when the generated code is compiled.
The compiler does not parse the style text. A CSS error is reported when the document first updates with the component mounted, naming the scope, line and column.