Architecture Overview

This page explains how Vize's packages reach the Rust compiler and developer tools. Use it to identify the part that owns a behavior before debugging an integration or contributing a fix. For installing Vize in an app, start with Getting Started.

Follow the relationship map from your entry point—for example, @vizejs/vite-plugin—to the crate responsible for the output. Then use the Source Guide to find files and the Crate Reference to identify APIs.

The diagrams describe the existing product pipeline under crates/. The experimental level pipeline lives separately under davinci/; its roadmap and migration gates are recorded in the level restructure decision. Internal architecture continues to change.

Project Relationship Map

JavaScript integrations call the native bindings; compiler and developer-tool crates reuse shared parsing and analysis infrastructure. Follow the arrows from the package you are working with.

This relationship map is about ownership and reuse, not every call edge. The important invariant is that parser, AST, and semantic analysis stay shared, while the compiler backends and developer tools remain replaceable workshops around that shared language model.

Lanes

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:
   • VDOM (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 Lanes

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

Sharing parsing and AST infrastructure reduces duplicated language handling. Compatibility still needs fixture and integration tests for each compiler and tool surface.

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.

The implementation workflow is documented in Language Engineering Practices, which maps parser, compiler, analyzer, type-checker, formatter, LSP, and release changes to the fixture, snapshot, parity, benchmark, and readiness evidence expected for review.

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

The existing product 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 VDOM output.

External Dependencies

Vize integrates with the broader Rust ecosystem for specialized tasks: