Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Using packages

Find and add

vard search bar chart        # by name, keywords, summary and exports
vard info charts             # before adding: versions, capabilities, API, tests
vard add charts              # exact name; writes vard.toml and vard.lock
vard doc charts              # AGENT.md + the API generated by the compiler
$ vard search chart
charts 1.0.0 [lan] — Bar charts drawn with Vard elements
    caps: none · exports: Badge BarChart · tests 1 ✓
details: vard info NAME · install: vard add NAME

$ vard add charts
added charts 1.0.0 (lan)
  caps: none
  api: 2 views — `vard doc charts`
vard.lock: + charts 1.0.0
vard.lock: + tailwind 1.0.0
next: vard check

Variants:

vard add charts@1.4                 # minimum version 1.4.0 on the 1.x line
vard add auth --registry acme       # from a specific registry
vard add ui --path ../ui            # a local package (monorepo)
vard add charts --git https://github.com/acme/charts --tag v1.4.0   # straight from git
vard add firebase --allow native    # approving a sensitive capability
vard remove charts

A typo never turns into installing something similar:

$ vard add chart
error P001: no package `chart` in registry `acme`; did you mean: charts?
  fix: search instead of guessing: vard search chart

An app’s vard.toml

[app]
name = "shop"

[dependencies]
charts = "1.4"                                 # >= 1.4.0, < 2.0.0
legacy = "0.3"                                 # 0.x: the 0.3.* line (as in Cargo)
exact = "=2.1.3"                               # exactly this version
auth = { version = "2", registry = "acme" }    # from the acme registry
ui = { path = "../ui" }                        # a local package
widgets = { git = "https://github.com/acme/widgets", tag = "v2.1.0" }
mono = { git = "../monorepo", branch = "main", dir = "packages/mono" }   # rev = "…" also works

[policy]
allow = ["native", "push"]                     # approved sensitive capabilities

[registries]
acme = "https://vard.acme.dev"                 # http(s) or a directory
default = "acme"                               # where dependencies without registry= come from

The manifest can be edited by hand: any vard command (check, run, test, doc) notices that vard.lock is stale and reinstalls, saying so in one line.

Registries are looked up in order: the project’s [registries] → ~/.vard/config.toml → the public registry vard (vardemin/vard-registry, served at https://vardemin.github.io/vard-registry) → builtin (the packages bundled with the toolchain, available offline). The default registry is vard unless default (or the VARD_REGISTRY variable) says otherwise; VARD_OFFLINE=1 removes the public registry and makes builtin the default. Each dependency comes from exactly one registry — its own registry = ... or the default — never “wherever it was found”: this rules out dependency confusion attacks.

Git dependencies

{ git = URL, tag | rev | branch = "...", dir = "sub/dir" } takes a package straight from a repository — any URL git understands, or a local path relative to vard.toml. The commit the reference resolves to is pinned in vard.lock together with the content hash of the package files, so a branch does not move under the project until vard update NAME re-resolves it:

$ vard update charts
~ charts 1.0.0 -> 1.1.0 (git 3f2a9c1e0b7d -> 8c41d0a2e9f3)

Git packages go through the same capability policy as registry packages. A package that depends on a git (or path) package cannot be published to a registry (P021): registries only reference registry versions.

New packages are quarantined

A package from a remote registry whose first version was published less than 72 hours ago is not installed without --allow-new (P024). Fresh packages are where look-alikes and typosquats live, so a person confirms them after a look at vard info NAME (owner, publication time, provenance — which CI run built the archive). vard search and the registry’s web page mark such packages NEW. The MCP tool vard_add has no --allow-new: an agent asks the user. Directory registries (your own) are not quarantined.

vard.lock

# vard.lock — written by `vard install`. Commit it; review caps= changes like code.
lock 1
root deps=charts
pkg charts 1.0.0 src=reg:acme sha256=100e077d… api=350f1ca96bc8 caps= deps=tailwind
pkg tailwind 1.0.0 src=builtin sha256=6d7a5aa6… api=386f0117f3f1 caps= deps=

One line per package, sorted — a diff reads like a review:

  • a new caps= value — the package gained a capability;
  • a new sha256= under the same version — content substitution (the manager marks it !);
  • api= — a short hash of the public API: equal hash = equal API.

Commit the lockfile. It does not choose versions — MVS does, from vard.toml.

Namespaces

After vard add, the package’s public names are visible in the app’s code without imports:

view App {
  state data: [Int] = [10, 40, 25]
  BarChart(values: data, max: 50)
}
SituationWhat happens
a name is both in your code and in a packageyours wins; the package keeps using its own internally
two direct dependencies export a nameE0231 — write charts.Badge(...) or tailwind.Badge(...)
a name from a transitive dependencyE0232 — add it explicitly (vard add NAME)
a _ name from someone else’s packageE0230 — private
a pkg.Name that does not existE0235, with a fix for a typo
two dependencies declare one native nameE0233

You can qualify views (ui.Card { }), types (state s: ui.Style), functions and constructors (geo.distance(a, b), ui.Style(size: 2)); std.Button is the std view.

Capabilities and policy

CapabilityMeaningSensitive
prefsreads/writes preferences (pref, prefGet)
linksopens URLs in other apps
sharethe system share sheet
deeplinksreceives deep links
secureKeychain / Keystore✓
permissionsasks for runtime permissions✓
pushtoken, notifications, push events✓
networkloads remote resources (https:// in code)✓
nativedeclares extern fn/event: runs the package’s native code✓

Sensitive capabilities need approval in [policy] allow. Without it, installation is refused:

error P008: not allowed by [policy]: firebase 1.0.0 needs native (declares extern fn/event: runs native code shipped with the package)
  fix: a person approves this: add to vard.toml `[policy] allow = ["native"]` or rerun with --allow native

--allow records the approval in [policy] — it lands in the diff and goes through review. The vard_add MCP tool does not accept --allow: the agent tells the user what the package needs, and a person decides.

Upgrading

vard update                 # every dependency — to the newest compatible versions
vard update charts --major  # across a major boundary
vard check --fix            # the packages' migrations are applied to your code
vard test
$ vard update charts --major
~ charts 1.0.0 -> 2.0.0
  API change: major
  ! ~ view BarChart: `max` removed, `scale` added
vard.lock: ~ charts 1.0.0 -> 2.0.0
next: vard check --fix (applies the packages' migrations), then vard test

$ vard check
app/app.vard:3:32 error E0234: `max` of `BarChart` was renamed to `scale` in charts 2.0.0
  3 | BarChart(values: [10, 50], max: 80)
  fix: `max` -> `scale` (auto: vard check --fix)

vard update changes the requirements in vard.toml (visible in the diff), then reinstalls.

Packages in headless mode

A package’s externs answer with values from its [sim] (for example, authCurrentUser → nil); the rest stay pending until a test says resolve/send. mock in a test overrides [sim]. That is why vard run works right after vard add — even for a package wrapping a native SDK.

Diagnostics in package code

Package files are shown as @name/file.vard:LINE. Packages’ warnings are not printed (that is the author’s business); errors are. vard check --fix never writes into package files: they are inputs from the cache (~/.vard/cache/pkgs/).