Architecture Overview

⚠️ Work in Progress: Vize is under active development and is not yet ready for production use. Internal architecture may change as the project evolves.

Vize is built as a modular Rust workspace where each crate handles a specific concern. The architecture follows a pipeline model, transforming Vue SFC source code through parsing, analysis, and compilation stages.

Pipeline

Stage Details

1. Source — A .vue file containing <template>, <script>, and <style> blocks

2. Armature (Parser) — Tokenizes the raw source into a stream of tokens, then parses them into a structured AST. The tokenizer handles Vue-specific syntax: directives (v-if, v-for, v-bind), expression interpolation ({{ }}), and SFC block boundaries.

3. Relief (AST) — The intermediate representation. All downstream stages operate on this shared AST, eliminating redundant parsing.

4. Croquis (Semantic Analysis) — Resolves template expressions, tracks variable scopes, detects binding types (setup, data, props, inject), and validates expression correctness. Uses OXC for JavaScript/TypeScript AST parsing.

5. Atelier (Compilation) — Transforms the analyzed AST into JavaScript output. Three backends serve different targets:

   • DOM (vize_atelier_dom) — createVNode/h calls with patch flag optimization and static hoisting

   • Vapor (vize_atelier_vapor) — Fine-grained reactive code with direct DOM manipulation (no VDOM)

   • SSR (vize_atelier_ssr) — String concatenation with hydration markers

6. Output — Generated JavaScript code with source maps

Tool Pipeline

Beyond compilation, Vize provides additional tools that reuse the same parsing and analysis infrastructure:

Because all tools share the same parser and AST, they have a consistent understanding of your code. A lint rule in Patina operates on the same AST nodes as the compiler in Atelier — there's no risk of parser disagreement.

For type checking, vize_canon adds one more step: it generates virtual TypeScript from Vue SFCs and asks Corsa project sessions from corsa-bind for native diagnostics, then maps those results back onto the original files.

Crate Responsibilities

The gallery UI and dev-server integration for Musea live in the JavaScript package @vizejs/vite-plugin-musea; the Rust crate focuses on the parsing and generation core.

Naming Convention

Vize crates are named after art and sculpture terminology, reflecting how each component shapes and transforms Vue code. This naming system is more than aesthetic — it encodes the role and relationships between crates. See Philosophy for the full rationale.

Why Art Terminology?

The analogy between software compilation and artistic creation is surprisingly deep:

• A parser (Armature) provides the internal skeleton — the structure that everything else builds upon, just as a sculptor's armature supports the clay

• Semantic analysis (Croquis) is like a quick sketch — it captures the essential meaning without committing to a final form

• The compiler (Atelier) is a workshop where raw material is transformed into a finished work

• The AST (Relief) is a projection — it gives three-dimensional structure to what was originally flat text

• Bindings (Vitrine) are a glass display case — they let you see and interact with the work inside without directly touching it

• The linter (Patina) examines the surface finish — finding imperfections that affect the overall quality

• The formatter (Glyph) ensures consistent proportions — like a typographer carving letterforms with precise spacing

This naming convention makes the crate hierarchy intuitive: when you see vize_atelier_dom, you immediately understand it is a workshop that produces DOM output.

External Dependencies

Vize integrates with the broader Rust ecosystem for specialized tasks: