proto v0.51 - Unstable lockfiles and plugin registries
With this release, we're excited to introduce two major features that pave the way for proto's future!
Unstable lockfile support
Lockfiles have been requested by the community since proto's inception, but adopting them has been a non-trivial task, as it requires touching almost every aspect of proto. With that said, we've been slowly reworking the internals to support lockfiles, and with this release, we're introducing unstable support for them!
If you're unaware of what lockfiles are, they allow you to pin the exact version (and checksum) of a tool that is installed, ensuring that your development environment is consistent and reproducible. If you've used package managers like npm, Cargo, or uv, you're likely familiar with this concept.
In proto, the concept of lockfiles is mostly the same, but the manner in which they are created and
updated may differ based on other tools. To start, lockfiles in proto are opt-in and can be
enabled with the new settings.unstable-lockfile setting in
.prototools.
[settings]
unstable-lockfile = true
This will create a .protolock file in the current directory, relative to the .prototools file.
In effect, this locks that directory and all of its subdirectories. As a side-effect, nested
lockfiles are not supported.
To demonstrate how lockfiles work, installing the following tools with proto install...
bun = "1.2.0"
deno = "2.4.0"
node = "22.17.0"
[settings]
unstable-lockfile = true
... would generate the following .protolock file:
# Generated by proto. Do not modify!
[[tools.bun]]
spec = "1.2.0"
version = "1.2.0"
checksum = "sha256:fa72173cb2220d00e2d2650fefdc0b5b37bfd8bb33d8d671b50efb409c2f5745"
[[tools.deno]]
spec = "2.4.0"
version = "2.4.0"
checksum = "sha256:c913d018d64c48dcc5b7b90d844efb6d017595a7c1e237f89141df1b3ef8b962"
[[tools.node]]
spec = "22.17.0"
version = "22.17.0"
checksum = "sha256:cc9cc294eaf782dd93c8c51f460da610cc35753c6a9947411731524d16e97914"
Updated workflows
The proto run (shims),
proto install, and
proto uninstall commands have been updated to support lockfiles.
When running or installing tools and a matching specification exists in the lockfile, the locked
version will be inherited even if there's a newer version upstream, and the tool's checksum will be
validated when available. These checks can be bypassed with the new --update-lockfile flag
(install only).
Inversely, when uninstalling tools, the lockfile will be updated to remove any matching specification records.
Still a work in progress
We are marking lockfiles as unstable as they have not been fully implemented or thoroughly tested.
There are other commands like proto outdated and
proto status that are not lockfile aware yet, but will be in the
future.
But please, give them a whirl and let us know what you think!
Unstable OCI registries for plugin storage
Another important feature that is necessary for proto's success is support for an official plugin registry. Before we get to that, we need to lay the groundwork for how plugins are stored and distributed. With this release, we're introducing unstable support for OCI registries as a storage mechanism for plugins. If you're unfamiliar with OCI registries, they are a standard for storing and distributing container images (Docker), but can also be used to store other types of artifacts, in this case, WASM plugins.
To support registries, we have introduced a new
settings.unstable-registries setting in .prototools,
which allows you to configure a list of registries to query for applicable plugins. For example:
[settings]
unstable-registries = [
{ registry: "ghcr.io", namespace: "moonrepo" }
]
Additionally, we are introducing a new registry:// plugin locator, which allows you to configure a
plugin by its OCI reference.
[plugins]
# Longform with tag
bun = "registry://ghcr.io/moonrepo/bun_tool:v1.2.3"
# Longform without tag
bun = "registry://ghcr.io/moonrepo/bun_tool"
# Shortform with tag
bun = "registry://bun_tool:v1.2.3"
# Shortform without tag
bun = "registry://bun_tool"
How it works
Using a container registry to store plugins seems odd at first, but it actually allows us to leverage existing specifications, infrastructure, and tools to manage and distribute plugins. We don't want to re-invent the wheel here, so why not use something that most of the industry is already using?
With that said, how does this work in proto? Since we are not a container image, we use the artifact portion of the specification instead. Primarily, plugins are stored in layers! The blob/content of WASM, TOML, JSON, and YAML plugins are stored in CAS, and referenced in layers by a sha256 digest.
As for annotations, we support the OCI standard annotations, but will also support moonrepo-specific annotations in the future.
At this time, we do not provide a mechanism for uploading plugins to a registry. You'll need to do that manually.
Official registry?
We do have plans to support an official moonrepo plugin registry, for both proto and moon. We are in the process of investigating solutions to this and will provide more details soon.
Other changes
View the official release for a full list of changes.
- Removed
--canaryfromproto install, just usecanaryas the version specifier instead.
Looking for contributors
We have a lot of cool stuff planned for proto, like backend plugins, more official tools, improved workflows, an official registry, and more! So if you're interested in Rust or WASM, we would love and appreciate your help. Feel free to ping us on Discord!