Skip to main content

Dependencies

Rank dependencies are reusable packages of pure .rank modules. Declare them in [dependencies], then import them under the alias you chose in rank.toml.

A dependency is not a provider. Dependencies do not declare [provider], do not have a host runtime entrypoint, and do not request provider capabilities. Use a dependency for shared types, helper functions, transforms, and schemas. Use a provider when the package needs host-side behavior.

Dependencies can be loaded from:

  • a local path
  • an npm-compatible registry package
  • a git repository snapshot

Local dependencies​

Local dependencies are the simplest way to share Rank modules across nearby projects.

[dependencies]
shared = { path = "./vendor/shared" }
use shared::types::{ AppConfig }
use shared::render::{ render_config }

The dependency root needs a normal rank.toml with a [package] table and a source directory.

Publish to npm​

Registry-backed dependencies are ordinary npm packages that include Rank source files.

Minimal package layout:

rank-shared/
  rank.toml
  package.json
  src/
    index.rank
    types.rank

rank.toml:

manifestVersion = 1

[package]
name = "@acme/rank-shared"
version = "0.1.0"
source = "src"

package.json:

{
  "name": "@acme/rank-shared",
  "version": "0.1.0",
  "files": [
    "rank.toml",
    "src"
  ],
  "publishConfig": {
    "access": "public"
  }
}

Before publishing:

  1. Keep the package name and version aligned across rank.toml and package.json.
  2. Make sure the published tarball includes rank.toml and every .rank file under [package].source.
  3. If you publish a scoped package to the public npm registry, set publishConfig.access = "public".
  4. Run npm pack --dry-run, then publish with npm publish.

Consumers can then install the dependency directly from the registry in rank.toml:

[dependencies]
shared = { registry = "npm", package = "@acme/rank-shared", version = "0.1.0" }

If registry is omitted, Rank uses the default registry or a matching [registryScopes] rule.

Publish via git​

There is no separate Rank-specific git publish command. Publishing via git means pushing a repository that contains a normal Rank package, then referencing that repository from [dependencies].

Tag-based reference:

[dependencies]
shared = { git = "https://github.com/acme/rank-shared.git", tag = "v0.1.0" }

Commit-pinned reference:

[dependencies]
shared = { git = "https://github.com/acme/rank-shared.git", rev = "8d91b7c4e5d0c1a2b3f4e5d6c7b8a9b0c1d2e3f4" }

Monorepo package in a subdirectory:

[dependencies]
ui = { git = "ssh://git@github.com/acme/mono.git", rev = "6a1f0d9a8b7c6e5d4c3b2a190817161514131211", subdir = "packages/rank-ui" }

Use tag when you want a release workflow with named versions. Use rev when you want an exact immutable commit pin from the start. In both cases, the referenced repository still needs a normal rank.toml and [package] table at the package root.

Git-backed references are currently for [dependencies] only. Providers are path- or registry-backed, not git-backed.

Locking and caching​

Rank materializes registry packages and git snapshots on first use, or explicitly through rank sync ., and writes the result to rank.lock.

  • registry-backed dependencies lock to a concrete tarball and integrity hash
  • { git, tag } dependencies lock the requested tag plus the resolved commit
  • { git, rev } dependencies lock the requested and resolved commit

Commit rank.lock alongside rank.toml. That is what makes --offline and --frozen-lockfile reproducible in CI and deploy builds.

See also: