Workspaces & Lockfiles
A workspace is the root directory you work in: either a single package or a multi-package repository sharing one zena-lock.json lockfile.
Single-package vs. multi-package workspaces ​
A single package with a zena-package.json is already a workspace of one. To grow it into a multi-package workspace, add a workspace field to the root zena-package.json listing member directories or /* globs:
my-workspace/
zena-package.json # workspace root
zena-lock.json # shared lockfile for all workspace packages
packages/
core/
zena-package.json # name: "core"
main.zena
server/
zena-package.json # name: "server", depends on "core" via path
server.zena
{
"workspace": {
"packages": ["packages/*"]
}
}
- If the root
zena-package.jsonalso has aname, the root directory is a workspace package alongside the directories inworkspace.packages. - A package in a scope gives the scope in its own
name, such as"acme:server". The root's manifest gives its packages no scope.
Cross-package dependencies ​
Workspace packages depend on each other using path dependencies:
{
"name": "server",
"version": "1.0.0",
"description": "HTTP server built on core",
"license": "MIT",
"exports": {
"server": {}
},
"dependencies": {
"core": {"path": "../core"},
"router": {"did": "did:plc:routerrouterrouterrouter", "version": "^1.4.2"}
}
}
When you publish packages/server with zena pkg publish, the CLI replaces {"path": "../core"} in the published release record with core's did, and ^ and the version from packages/core/zena-package.json. Publish packages/core first so that it has a did and a published release on the registry.
Version selection ​
- Every dependency gives the versions it accepts as a range, in npm's syntax:
^1.4.2accepts1.4.2or any later1.xrelease, andzena pkg addwrites ranges of that form. - Selection installs as few versions of each package as the ranges asking for it allow: one version when one is in every range, and the highest such version. Two packages asking for
^1.0.0and~1.1.0share1.1.x. - When no one version is in every range, as for
^1.0.0and^2.0.0, selection installs more than one, and each package uses the highest selected version in its own range.zena pkg addandzena pkg updatelist such packages, and--duplicates warnorerrormakes them a warning or an error. - Once
zena-lock.jsonpins a version,zena pkg addkeeps it while the ranges allow; it lowers a version only to share one with another package, and says so with a warning. - New releases published upstream never enter your build automatically; versions only change when you run
zena pkg addorzena pkg update.
zena-lock.json ​
zena pkg add and zena pkg update write zena-lock.json at the workspace root. Do not edit it by hand, and always commit it to version control.
{
"lockfileVersion": 1,
"workspace": {
"packages/server": {"router": "did:plc:routerrouterrouterrouter@1.4.2"}
},
"resolved": {
"did:plc:routerrouterrouterrouter@1.4.2": {
"release": "bafyreiacaqzs6eeir3sujrd7r2olqqvv5pz7u6u52fnefvplhfizfbbngi",
"source": "bafkreibcvpjyzvstyfv4tuymmku7cbry7rzwusztpf3dappir5wh55kpsy",
"dependencies": {
"json": "did:web:json.example.com@2.1.0"
}
},
"did:web:json.example.com@2.1.0": {
"release": "bafyreiav6xyaoqpx6byrh727pez7ovomlndqwwqiatiwvvq5qlxfrlri6e",
"source": "bafkreidte7rh73ye5s7ctf2qzmb2ciuroxpoe2t6fgvknkstljoody2aba"
}
}
}
lockfileVersion is the version of the lockfile's format, a number of its own, unrelated to any package's version. It is 1. A zena that reads another version refuses the lockfile: given a newer one, upgrade zena; given an older one, or a lockfile without the field, delete it and run zena pkg update to write it again.
workspace gives, for each workspace package by its directory (. for the root), the pinned version each of its published dependencies stands for. Each entry under resolved is keyed by <did>@<version>, the package and the version selected, and records:
release: The CID of thedev.zena-lang.package.releaserecord in the package's atproto repository: a hash of the record, which names the version, the source archive and the dependencies.source: The CID of the source archive blob (application/vnd.ipld.car): a hash of its bytes.zena pkg fetchchecks the archive against it, and unpacks it intosources/<source-cid>in the package cache.dependencies: Map from the local names used inside that package's source to the<did>@<version>keys of its own dependencies, which are keys ofresolvedtoo.
Both CIDs are checksums: zena pkg fetch refuses a release record or an archive that does not match its pin, so a build from a committed zena-lock.json gets the same bytes or fails.