Defining a Package
A package is defined by the zena-package.json manifest at its root: its name, the metadata a registry shows, the libraries it exports, and its dependencies. To publish one, see Publishing Packages.
Example zena-package.json ​
{
"name": "acme:router",
"did": "did:plc:routerrouterrouterrouter",
"version": "1.4.2",
"description": "HTTP router for WebAssembly services",
"license": "MIT",
"main": "server",
"exports": {
"server": {},
"middleware": {"path": "middleware/index.zena"},
"transport": {
"virtual": {
"component": "transport/wasi.zena",
"js": "transport/fetch.zena"
}
}
},
"dependencies": {
"url": {"did": "did:plc:urlurlurlurlurlurlurlurl", "version": "^1.1.0"},
"internal-utils": {"path": "../internal-utils"}
}
}
Field reference ​
| Field | Type | Where | Description |
|---|---|---|---|
name |
string |
Any package | The package's name, after the scope it is created in: acme:router; suggested to dependents as their local name |
did |
string |
Any package | The package's AT Protocol DID, written by zena pkg publish or zena pkg create |
version |
string |
Any package | Semantic version (1.4.2, 2.0.0-rc.1) published by the next zena pkg publish |
description |
string |
Any package | One-sentence summary of the package; required to publish |
license |
string |
Any package | SPDX license expression (MIT, Apache-2.0, (MIT OR Apache-2.0)); required to publish |
source |
string |
Any package | The directory the package's libraries are in; src by default |
exports |
Record<string, Export> |
Any package | Libraries other packages may import as <local-name>/<library> |
main |
string |
Any package | The library an import of the package's name alone imports; main by default |
dependencies |
Record<string, Dependency> |
Any package | Packages imported by this package's libraries, keyed by local name |
workspace |
{packages: string[]} |
Workspace root | Directories or /* globs of workspace member packages |
scopes |
Record<string, string> |
Workspace root | Custom handle domains for scope:name lookups |
scopedNames |
boolean |
Workspace root | Whether zena pkg add names a package in a scope scope:name (the default) or by its own name |
All file and directory paths in zena-package.json are relative to the directory containing that manifest.
Package names (name) ​
A package name must be a valid lowercase DNS label:
- Lowercase ASCII letters (
a-z), digits (0-9), and hyphens (-). - Must start with a letter and must not end with
-. - Must not have
--as its third and fourth characters (reserved for punycode prefixes). - At most 63 characters.
zenais reserved for the Zena standard library.
Where the libraries are (source) ​
A package's libraries are in its src directory, and the manifest, README and license sit at its root:
router/
zena-package.json
README.md
src/
server.zena # router/server, and router, as main names it
middleware/
index.zena # router/middleware, as exports names it
test/
server_test.zena
A library's name is its path from src, without .zena. Set source to keep them elsewhere, such as "source": "." for libraries at the package's root.
Exporting libraries (exports) ​
Each key under exports declares a library that dependents can import as <package>/<library>. Entry files are relative to the source directory.
{
"exports": {
"array": {},
"url": {"path": "url/index.zena"},
"console": {
"virtual": {
"js": "console/none.zena",
"zena-js": "console/js.zena",
"component": "console/component.zena",
"zena-component": "console/component.zena"
}
}
}
}
{}(empty object): Resolves to<source>/<library-name>.zena, such assrc/array.zena.{"path": "..."}: Resolves to the specified entry file relative to thesourcedirectory. Other files in the package reached via relative imports (import {helper} from './internal.zena') remain private and cannot be imported directly by dependents.{"virtual": {...}}: Maps compilation targets (core,js,zena-js,component,zena-component) to target-specific entry files. When compiling with--target component, an import ofpkg:consoleresolves toconsole/component.zena.
Open vs. closed packages ​
- With
exports(closed): Only the libraries listed inexportscan be imported by other packages. - Without
exports(open): Every.zenafile under thesourcedirectory can be imported by its path from there (without.zena). Open packages are convenient for small internal workspace packages; published packages should declareexports.
Dependencies (dependencies) ​
Each key in dependencies is the local name used by imports inside this package. A dependency entry takes one of three forms:
1. Published package (did + version) ​
"router": {
"did": "did:plc:routerrouterrouterrouter",
"version": "^1.4.2"
}
Written automatically by zena pkg add. Names a published package by its DID and the range of versions this package accepts, in npm's syntax: ^1.4.2 accepts 1.4.2 and any later 1.x release, ~1.4.2 only 1.4.x, and 1.4.2 only that version.
2. Path dependency (path) ​
"shared": {
"path": "../shared"
}
Points to another package directory on disk containing a zena-package.json. Used for sibling packages in a workspace or local checkout testing. When a workspace package is published with zena pkg publish, its path dependencies are automatically converted into {did, version} entries in the published release record.
3. WIT dependency (wit) ​
"wasi-http": {
"wit": "./wit/http"
}
Synthesizes Zena interface declarations from a .wit file or directory for WebAssembly Component Model bindings. Because WIT paths refer to local disk, a published package cannot have a raw wit dependency; publish the WIT bindings as a Zena package instead.
Custom scope domains (scopes) ​
By default, zena pkg add scope:name resolves <name>.<scope>.pkg.zena-lang.dev (or the registry in ZENA_REGISTRY). If an organization hosts packages under its own domain, map the scope in the workspace root's zena-package.json:
{
"scopes": {
"widgets": "pkg.widgets.example.com"
}
}
With that mapping, zena pkg add widgets:button resolves button.pkg.widgets.example.com.
Names without their scope (scopedNames) ​
zena pkg add names a package in a scope by its scope:name, and imports read 'widgets:button/icons'. To name packages by their own names instead, and import 'button/icons', set scopedNames in the workspace root's zena-package.json:
{
"scopedNames": false
}
--name still gives any package the name you choose.