Creating a package
Structure, test, version, and publish a Valk package.
On this page
A Valk package is a directory with a valk.json file and a src/ folder, published as a Git repository with version tags. No registry upload step is required for vman to install it, and listing the repository on vpkg.dev makes it searchable.
Directory layout#
Give the package its own repository with src/, tests/, and an optional example/:
myformatter/
├── valk.json
├── src/
│ └── bytes.valk
├── tests/
│ ├── valk.json
│ └── basics.valk
└── example/
├── valk.json
└── main.valk
Put your library sources in src/. Subdirectories under src/ automatically become sub-namespaces: src/text/wrap.valk is imported as use myformatter.text.
Package configuration (valk.json)#
The root valk.json declares the package's import name, the compiler version used during development, and the lowest compiler version callers need:
{
"name": "myformatter",
"use": "0.8.10",
"require": {
"valk": {
"min": "0.8.10"
}
}
}
nameis the default namespace callers import (use myformatter). It must be a valid identifier (letters, digits, underscores); when omitted,vmanfalls back to the repository name.usepins the compiler version for contributors runningvman use.require.valk.minsets the lowest Valk version this package supports. When someone runsvman install,vmanautomatically picks the newest tag whose minimum compiler version matches their project.
If your package depends on other packages, install them with vman install from the package root. vman records them under dependencies in valk.json, and installs them transitively when someone installs your package.
Public API and visibility#
Only declarations marked with + are visible to callers that import your package. Unmarked declarations are shared across files inside your package, - restricts a declaration to its own file, and ~ makes a property readable outside its file without allowing writes:
/// Formats a byte count as a readable string, such as `"1.5 KB"`.
+ fn format_bytes(bytes: uint) String {
if bytes < 1024 : return "%{bytes} B"
if bytes < 1024 * 1024 : return format_unit(bytes, 1024.0, "KB")
return format_unit(bytes, 1024.0 * 1024.0, "MB")
}
fn format_unit(bytes: uint, divisor: f64, unit: String) String {
let value = bytes.to(f64) / divisor
return "%{value:.1f} %{unit}"
}
Write /// documentation comments on public types, functions, methods, and properties. Generate standalone API documentation from the package root with:
valk doc . -o docs/api.md --markdown --no-private
Tests and examples#
Give tests/ and example/ their own valk.json that points to the parent directory as a local dependency. That way your tests import the package exactly the way an external caller does (use myformatter), verifying your + visibility boundaries:
{
"src": ".",
"dependencies": {
"myformatter": {
"src": "../"
}
}
}
Then write tests in tests/basics.valk (avoid naming a test file after the package itself, since tests/myformatter.valk would shadow the myformatter dependency):
use myformatter
test "format_bytes formats bytes, kilobytes, and megabytes" {
assert(myformatter.format_bytes(512) == "512 B")
assert(myformatter.format_bytes(1536) == "1.5 KB")
assert(myformatter.format_bytes(2 * 1024 * 1024) == "2.0 MB")
}
Run tests and check for warnings from the package root:
valk build ./src --lint --deny-warnings
valk build ./tests --test --run
valk build ./example --run
Versioning and publishing#
vman resolves package versions from Git tags using three-part version numbers (major.minor.patch, without a leading v):
git add -A
git commit -m "Initial release"
git tag 0.1.0
git push origin main --tags
Once pushed, anyone can install the package directly from its repository URL:
vman install github.com/you/myformatter
vman clones the repository, picks the newest compatible tag, copies the files into vendor/, and records both the version and commit hash in the caller's valk.json so installs stay reproducible.
To make the package discoverable by search and track each version's minimum Valk requirement, list it on vpkg.dev:
- Create an account and log in at vpkg.dev.
- Open your Account page, paste the GitHub repository URL under Add package, and submit.
- Confirm ownership if prompted. Every tag is listed as a version automatically.
Continuous integration#
Add .gitignore entries for vendor/, tests/vendor/, example/vendor/, and debug/, and run linting, tests, and doc checks in CI:
name: ci
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install vman and valk
run: |
curl -fL -o vman.tar.gz https://files.valk-cdn.dev/releases/vman/vman-linux-x64.tar.gz
mkdir -p "$HOME/vman"
tar -xf vman.tar.gz -C "$HOME/vman"
echo "$HOME/vman/bin" >> "$GITHUB_PATH"
echo "$HOME/.vman/bin" >> "$GITHUB_PATH"
"$HOME/vman/bin/vman" use 0.8.10
- run: valk build ./src --lint --deny-warnings
- run: valk build ./tests --test --run
If your package has dependencies in valk.json, add a vman install step before building.

