The Vilan documentation
How to use the Vilan language, its standard library, and the frameworks
built on top of it. If you’re wondering where something lives: this book
is about using Vilan. Design history and rationale live in the
vilan-lang/proposals repository.
Brand new? Hello Vilan installs the toolchain and
gets a program running in a couple of minutes. Everything in this book
assumes only that the vilan command is on your PATH.
Parts
- Tour: the language itself, taught informally. Start with Coming from JavaScript if that’s your background, then read in order. Come back any time you need a syntax reminder. Nothing in the tour assumes you know the other parts.
- Guides: the frameworks, task by task. Reactive state, building UI, styling, routing, talking to a server. Each guide reads front to back and links into the reference for exact signatures.
- std reference: the standard library, signatures first. Go here to answer “what were the parameters again?”.
- Specification: the formal definition. Grammar, type rules, the memory model, execution. This is the advanced tier. The tour teaches; the spec defines; where they disagree, the spec wins.
- Appendix: the CLI reference, the editor (what the language server gives you), the error index (“you saw this message, go here”), the gotchas checklist, and the glossary.
Where this book lives
The published copy is at https://vilan-lang.org/docs/, with search and
a sidebar, always built from the latest main. That is the copy to link
to and the one most readers want.
The source is markdown in the
repository under vilan/docs/, so
everything also reads fine as plain files. If you have the repository
checked out, cargo install mdbook --version 0.5.4 --locked once and then
mdbook serve vilan/docs gives you the same site locally with live reload.
The version is a pin, not a suggestion: mdBook’s heading-id algorithm
decides every anchor on the published site, and three things in this tree are
held to v0.5.4’s answer — std::markdown’s parser (the book-wide anchor
golden, crates/vilan-core/tests/markdown_anchors.golden), the language
server’s keyword-hover deep links (book_sync.rs), and the site build itself
(the pages repo fetches the v0.5.4 release by sha256). A newer renderer can
move an anchor, and a moved anchor is a broken link.
Conventions
- Examples are complete programs unless explicitly labelled a fragment:
copy,
vilan build, run. - Every example compiles as part of the test suite (
cargo test --test docs): a fenced```vilanblock must compile for the Node target,```vilan,browserfor the browser target,```vilan,noruncompiles but needs external services to actually run, and```vilan,fragmentis prose-only (used sparingly, always labelled). - Maintenance rule: a change to std, a framework, or the language updates the affected docs page in the same commit.
Contents
Tour
| Chapter | Covers |
|---|---|
| Coming from JavaScript | the three big shifts, a JS→Vilan phrasebook |
| Hello Vilan | installing, the CLI, vilan.toml, packages & workspaces, imports |
| Projects & dependencies | manifests, workspaces, declaring and resolving dependencies |
| Values & types | bindings, primitives & numeric widths, strings & interpolation, tuples, collections |
| Functions & closures | fun, closure types, named-fn coercion, async closures and their seams, context clauses |
| Data & traits | structs, enums, impl, generics & bounds, traits, derives |
| Control flow | match/is, loops, ret, Option/Result idioms, ! and ?. |
| The memory model | value semantics, views, mut/own, Shared, Arena/Handle |
| Async | implicit await, async expr spawn, promises, timers |
| Resources | resource, moves & loans, Drop, drop(x), Option.take, Database, OwnedNursery |
| Macros & const | const evaluation, derive macros, macro { … } blocks |
| Platforms | std layers, full-stack packages, externs, assets |
Guides
| Chapter | Covers |
|---|---|
| Reactive state | signals, derived state, effects, ownership & disposal, turns, optimistic/Optimistic, Draft |
| Building UI | view chaining, binds, events, lists, conditionals, mounting |
| Styling | const typed styles, lengths/colors, dynamic values |
| Routing | enum routes, parse/href, link, swap, navigation |
| Services & RPC | [service]/[rpc]/[expose], Wire, mirrors, reconnection, the server side |
| Persistence & the server | std::db (SQLite), the http server, files, the process |
| Server-side rendering | render-and-replace, one component on both legs, the HTML shell |
| A full-stack walkthrough | the Notes app end to end: every layer meeting, quoted from a real, tested example |
| The dev loop | run --watch, hot module replacement, what carries across a swap |
std reference
| Page | Modules |
|---|---|
| collections | List, Map, Set, Range, Iterator |
| option & result | Option, Result and their method sets |
| strings | str, Display, Debug, Into |
| numbers | the sized numerics, math, random |
| traits | compare, default, the operator traits, Try/Lift |
| cells | Shared, Arena/Handle |
| time | Instant, Duration, timers |
| encoding | json, wire, binary, bytes, base64 |
| net | fetch, ws |
| reactive | the full std::reactive API |
| style | the full std::style API |
| rpc | std::rpc: transports, clients, frames |
| browser | std::dom, std::ui, std::router, std::storage |
| dev / HMR | std::dev: stash/take, on_teardown, hmr_active |
| process | db, http, fs, build, document, process, rpc_server, watch |
| misc | io, task, promise, context, crypto, jwt, asset |
Specification
| Chapter | Defines |
|---|---|
| §1 Introduction | conformance, notation, processing phases |
| §2 Lexical structure | tokens, keywords, literals, operators |
| §3 Grammar | the full EBNF, precedence, patterns, types |
| §4 Names & modules | scopes, resolution, imports, namespaces |
| §5 The type system | types, generics & inference, traits, coercions, !/?. |
| §6 The memory model | the four rules, views, projections, the await rule |
| §7 Execution & async | entrypoint, evaluation order, the async model |
| §8 Contexts | ambient values: run/get, coverage, injected closures |
| §9 Const evaluation | compile-time values, the const environment, assets |
| §10 Macros | attribute/derive/block macros, macro_std, splicing |
| §11 Platform model & manifests | layers, coloring, fences, vilan.toml |
| §A Appendix | precedence & keyword tables, lang items |