Yarn

Yarn is supported read-only. Install and run work; any command that would rewrite yarn.lock refuses before the engine touches anything:

$ nub add lodash
Error: nub add: refusing to modify yarn.lock —
       adding a dependency re-resolves and rewrites yarn.lock
  Run it with yarn directly:
    yarn add lodash

Keep using yarn for anything that changes the dependency graph.

Both formats are read:

• Classic — yarn.lock with no __metadata block (Yarn 1.x).
• Berry — the __metadata / version format (Yarn 2+).

Configuration

Running a Yarn project

nub install        # reads yarn.lock, links node_modules, runs lifecycle scripts
nub ci             # frozen install: yarn.lock is law; drift is a hard error
nub run <script>   # runs package.json scripts
nubx <bin>         # one-off binary execution

Nub applies top-level resolutions in package.json the way Yarn does. Top-level overrides is npm and Bun's pin field: Yarn ignores it, and so does Nub under a Yarn incumbent, so put pins in resolutions.

Refused commands

Run these with yarn:

nub add <pkg>       # → yarn add
nub remove <pkg>    # → yarn remove
nub update          # → yarn upgrade
nub dedupe          # → yarn dedupe

The same gate fires on an install / ci that would rewrite the lockfile rather than just read it: a project that declares Yarn but has no yarn.lock yet, nub install --force / --no-frozen-lockfile / --lockfile-only, or a yarn.lock that no longer satisfies package.json. Run yarn install for those.

There is no path that converts to yarn.lock. The nub import command produces a pnpm-lock.yaml:

$ nub import        # in a yarn project
Imported 2 packages from yarn.lock to pnpm-lock.yaml

Config files

Nub reads .npmrc for registry, auth, scopes, CA, and proxy settings. In a Yarn-incumbent project, Nub also reads part of .yarnrc.yml:

• npmRegistryServer becomes the default registry.
• npmScopes.<scope>.npmRegistryServer becomes a scoped registry.
• npmAuthToken and npmAuthIdent are applied when they can be attached to a known registry, including npmRegistries entries.
• Scope-level auth (npmScopes.<scope>.npmAuthToken / npmAuthIdent) is applied only when that scope has its own unique custom npmRegistryServer. Scope auth with no custom registry, with a shared registry, or with a registry that also has an npmRegistries entry is skipped rather than widened into registry-wide credentials.
• httpsCaFilePath becomes the CA file, and networkSettings.<host>.httpsCaFilePath becomes the per-host CA.
• httpProxy / httpsProxy set the proxy, and enableStrictSsl maps to strict-SSL.
• packageExtensions adds dependency and peer metadata to resolved packages, and dependenciesMeta.*.built gates which packages run build scripts.
• YARN_NPM_REGISTRY_SERVER, YARN_NPM_AUTH_TOKEN, YARN_NPM_AUTH_IDENT, and the top-level CA, proxy, and strict-SSL env values are recognized above .yarnrc.yml for the same subset. Top-level auth env values attach when the environment also supplies the registry they belong to; scoped and map-shaped Yarn env config is not translated.

Yarn's nodeLinker, nmHoistingLimits, nmMode, and YARN_NODE_LINKER have no effect under Nub — see layout settings.

Nub reads .yarnrc.yml only when the project is Yarn-owned, by packageManager: "yarn@..." or a Yarn lockfile. A Nub-identity project does not read Yarn config.

npmRegistryServer: https://registry.internal/
npmScopes:
  myorg:
    npmRegistryServer: https://npm.myorg.dev/
    npmAuthToken: "<token>"
npmRegistries:
  "https://npm.myorg.dev":
    npmAuthIdent: "user:pass"

Nub reads the global ~/.yarnrc.yml plus any project .yarnrc.yml files from the workspace root down to the current project directory; nearer project files win. Still ignored: per-host networkSettings proxies (the proxy Nub applies is process-wide), constraints, plugins, patch-folder config, and Yarn cache layout.

Classic .yarnrc (Yarn 1) is read for its registry and auth fields. Its keys are already npmrc-shaped, so Nub reads them directly:

registry "https://registry.internal/"
"@myorg:registry" "https://npm.myorg.dev/"
"//npm.myorg.dev/:_authToken" "<token>"

Discovery mirrors classic Yarn: the global ~/.yarnrc plus any project .yarnrc files from filesystem root down to the current directory, nearer files winning. Only the default registry, scoped registries, and registry-keyed or top-level auth (_authToken / _auth) are read; every other classic key — network-timeout, save-prefix, yarn-offline-mirror, --flag argument lines, and so on — is ignored.

Node linkers

Yarn's nodeLinker does not select the layout Nub installs. A Yarn-owned project can set install.linker in nub.jsonc, put node-linker in .npmrc, or pass --node-linker for one command.

node-linker=hoisted

Plug'n'Play is the exception: it is refused, not ignored. A PnP project has no node_modules tree for Nub to install into, and Yarn Berry defaults to PnP when nodeLinker is absent, so both nub install and nub ci abort before mutation with ERR_NUB_PNP_UNSUPPORTED. Set nodeLinker: node-modules to install with Nub.

The Nub runtime fully supports Plug'n'Play. If a project was already installed by Yarn in PnP mode, Nub can run it — nub <file>, nub run, and nubx honor .pnp.cjs across all supported Node versions. What Nub cannot do is produce a PnP install. So the supported workflow for a PnP project is: install with yarn, run with nub. See Plug'n'Play resolution for how Nub resolves a PnP project at runtime.

Gaps

Nub does not fully support these Yarn settings:

• Per-host networkSettings proxies — the proxy Nub applies is process-wide, not per registry host.
• Layout settings — nodeLinker, nmHoistingLimits, nmMode, and YARN_NODE_LINKER have no effect. Set layout in nub.jsonc or .npmrc instead.
• Yarn PnP (nodeLinker: pnp) — both nub install and nub ci abort before mutation with ERR_NUB_PNP_UNSUPPORTED. Install with Yarn and run with Nub, or select nodeLinker: node-modules.