#Projects and Packages

Source imports describe dependencies. Project configuration chooses local overrides and execution authority; a lockfile records resolved package contents. Rig does not require a separate dependency manifest duplicating the imports.

#Project Files

A project commonly contains:

main.rig
rig.lock
.rig/
  config.toml
  overrides.toml
  packages/

config.toml selects capabilities. overrides.toml maps package identities to local contents. packages/ is a cache, not the source of the project's dependency declarations.

The CLI searches upward from the entry directory for the nearest applicable project files. Override targets and capability mount paths are relative to the project directory containing .rig/, not the process working directory. Without existing configuration, defaults apply without creating config files.

#Package References

An exact reference such as pkg:example/math@1.0.0 identifies a package. In a require form, from="pkg:example/math@1.0.0" selects its root API. For a source package, that API comes from its lib.rig module.

There are two implementation forms:

Resolution determines the package kind. Source code does not switch to another locator scheme when a dependency changes representation, though its selected API must still be compatible.

WIT packages supply interface definitions rather than executable implementations. An exact reference such as wasi:cli/stdout@0.3.0 brings wasi:cli@0.3.0 into the same package graph, cache, and lockfile system. The host must separately implement the required interface.

#Local Overrides

To develop example/math locally, put a source package at vendor/math/lib.rig:

(define double:(Fn Int Int) double=(fn value:Int do=(add value value))) (provide double:(Fn Int Int))

Create .rig/overrides.toml:

[packages]
"pkg:example/math@1.0.0" = "vendor/math"

Your importing file can then use (require double:(Fn Int Int) from="pkg:example/math@1.0.0"). No registry publication is needed for this local workflow. Changes to the override are read from their source rather than copied into a package cache.

The same table can point to a compiled .wasm package or a binary WIT definition. Getting Started uses a WIT override for the downloadable WASI contract.

#Resolution and Locks

The native CLI resolves packages in this order:

  1. Project-local overrides.
  2. The local package store, normally .rig/packages.
  3. A configured registry for missing packages.

RIG_PKG_ROOT selects another store location. Registry transport uses the shared wasm-pkg configuration; Rig supplies a default GHCR mapping for its own rig package namespace, while explicit user configuration takes precedence. Resolution is not a search for interchangeable implementations.

rig deps fetch main.rig resolves reachable packages and updates rig.lock. Fetch-backed build and run also update it after success. The lock records exact references, content kind, origin, digest, and dependency edges; it does not store local override paths.

The lock is project-wide. Fetching another entry merges its closure rather than replacing unrelated entries. A locked build or run checks only the packages reachable from its selected entry, requires an existing lockfile, and does not fetch missing contents. Local overrides remain development policy outside the lock.

The lockfile checks dependency identity and integrity. It does not make compile-time effects reproducible or grant authority to execute them.

#Selecting Named Interfaces

A Component package may export root functions and named interface instances. Selection is always explicit. For example:

pkg:acme/memory-store@2.0.0#example:storage/store@1.0.0

Before # is the implementation package, used for resolution, overrides, and locking. After it is the exact exported interface-instance name. The two versions describe different things and need not match. An inline instance name such as #store is also possible when that is the actual export name.

A bare package reference selects roots only, even if the package exports exactly one interface. A contract-only reference such as wasi:cli/stdout@0.3.0 remains a host requirement; it does not select whichever supplied package happens to implement that interface.

#Execution and Publication

Local execution composes selected dependencies and uses one instance per package within the request. A new request starts fresh. Component dependencies may have startup effects even when an imported function is not called. Source initializers retain their own stage and source ordering; unrelated discovered packages are not initialized.

Use rig build main.rig --external-deps when another environment will compose the package imports. Otherwise ordinary build and run compose resolved implementations while preserving residual host requirements and their authority boundaries.

Source packages publish ordinary .rig files as an archive; Component packages publish their compiled boundary API. Publishing needs registry configuration and credentials. The CLI has separate commands for each representation.

In browser embeddings, supplied contents and explicit HTTP loaders feed the same compiler-owned resolution model. Remote endpoints must permit CORS; native OCI credentials and registry configuration are not automatically available to browser code.