Package Specs

A package spec is the value on the right-hand side of a dependencies entry — the string that tells utoo where a package comes from. utoo supports the full set of specifiers that npm / pnpm / yarn accept, plus a couple of utoo-specific additions.

Any spec can be used both in package.json and on the command line:

ut install lodash@^4.17.21
ut install vite@npm:rolldown-vite@^7.1.13
ut install "foo@file:./local-pkg"
ut install "xlsx@https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"

Registry

The default. Strings without a protocol prefix are parsed as semver ranges and looked up in the configured npm registry:

{
  "dependencies": {
    "lodash": "^4.17.21",
    "react": "18.3.0",
    "next": "canary"
  }
}

Supported forms: ^1.2.3, ~1.2.3, >=1.0.0 <2.0.0, exact versions, and npm dist tags  like latest, next, canary.

When you add a package without a version, utoo normalizes the spec in package.json:

npm: alias

Install a package under a different name, or pin a package name to a fork. The alias on the left, the real package/version on the right:

{
  "dependencies": {
    "vite": "npm:rolldown-vite@^7.1.13"
  }
}

node_modules/vite will contain rolldown-vite’s files, and require('vite') resolves to it.

workspace:

Reference a package that lives inside the current monorepo. Resolution happens at graph build time, before any registry call.

{
  "dependencies": {
    "@my-monorepo/ui": "workspace:*",
    "@my-monorepo/utils": "workspace:^1.0.0"
  }
}

See Workspaces for the full monorepo story.

catalog:

Reference a version declared in the project’s .utoo.toml catalog. Lets one edit in .utoo.toml update every workspace that consumes the dependency.

{
  "dependencies": {
    "react": "catalog:",
    "debug": "catalog:legacy"
  }
}

See Catalog for default vs. named catalogs, update flow, and scope rules. For forcing a version on transitive deps instead, see Overrides.

file: tarball

Consume a .tgz from disk. Useful for local smoke-testing a package before publishing:

{
  "dependencies": {
    "foo": "file:./vendor/foo-1.2.3.tgz"
  }
}

The tarball is extracted into <cache>/<name>/_file_<sha256(abs-path)[:16]>/package/. The cache key is the tarball’s absolute path, so copies in different directories do not collide.

file: directory

Consume a local source directory. utoo copies the tree into the cache (excluding node_modules and .git), so updates to the source do not auto-propagate — re-run ut install after source changes.

{
  "dependencies": {
    "foo": "file:../local-pkg"
  }
}

http(s):// tarball

Consume a remote .tgz URL directly:

{
  "dependencies": {
    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
  }
}

Transient failures (network, 5xx, 429) are retried up to 5× with backoff (100 ms, 200 ms, 500 ms, 1 s, 2 s). The tarball is cached at <cache>/<name>/_http_<sha256(url)[:16]>/ so subsequent installs hit the cache with no network work.

package-lock.json records the URL as the resolved field.

Git

Any URL that Git itself understands works: git+https, git+ssh, git://. A #<ref> fragment pins to a branch, tag, or commit SHA:

{
  "dependencies": {
    "foo": "git+https://github.com/user/foo.git#v1.0.0",
    "bar": "git+ssh://git@internal.git/org/bar.git#main"
  }
}

github: shorthand

A shorthand for public GitHub repositories:

{
  "dependencies": {
    "foo": "github:user/repo",
    "bar": "github:user/repo#semver:^1.0.0"
  }
}

Equivalent to the corresponding git+https://github.com/... URL.