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

Nub reads yarn.lock to install and run a project but never writes it. 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+).

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

Top-level resolutions in package.json is honored — Nub applies it the way Yarn does. The packageManager field is what tells Nub the project is a Yarn project.

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 Nub's own 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 a small .yarnrc.yml subset that maps cleanly onto its existing registry and linker model:

• 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.
• nodeLinker: node-modules maps to Nub's hoisted linker.
• nodeLinker: pnpm maps to Nub's isolated linker.
• 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 is merged the same way pnpm's is, and dependenciesMeta.*.built gates which packages run build scripts.
• YARN_NPM_REGISTRY_SERVER, YARN_NPM_AUTH_TOKEN, YARN_NPM_AUTH_IDENT, YARN_NODE_LINKER, 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 env surface also supplies the registry they belong to; scoped and map-shaped Yarn env config is not translated.

The same brand boundary applies as everywhere else: .yarnrc.yml is read only when the project is actually Yarn-owned, by packageManager: "yarn@..." or a Yarn lockfile. Nub-identity projects do not consume Yarn config.

# .yarnrc.yml — supported subset in a Yarn-incumbent project
npmRegistryServer: https://registry.internal/
npmScopes:
  myorg:
    npmRegistryServer: https://npm.myorg.dev/
    npmAuthToken: "<token>"
npmRegistries:
  "https://npm.myorg.dev":
    npmAuthIdent: "user:pass"
nodeLinker: node-modules

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. The support is intentionally narrow. Still ignored: supportedArchitectures, npmAlwaysAuth, file-path TLS client cert and key (httpsKeyFilePath / httpsCertFilePath — Nub takes inline PEM only), per-host networkSettings proxies (the proxy Nub applies is process-wide), constraints, plugins, patch-folder config, and Yarn cache layout.

Classic .yarnrc (Yarn 1) gets the same basic treatment for its core registry and auth fields. Its keys are already npmrc-shaped, so Nub reads them directly:

# .yarnrc — supported core fields in a Yarn-incumbent project
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

Nub maps the Yarn linker settings it can represent:

# .yarnrc.yml
nodeLinker: node-modules  # hoisted node_modules
nodeLinker: pnpm          # isolated symlink layout
nodeLinker: pnp           # install generation is not supported

Yarn Berry defaults to PnP when nodeLinker is absent, so a Berry project with no linker setting is treated like a PnP project for install-generation purposes.

Nub-the-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

Several Yarn package.json and .yarnrc.yml fields still have no effect under Nub:

• supportedArchitectures — Yarn's platform/arch download controls are not read.
• npmAlwaysAuth — no Nub equivalent.
• httpsKeyFilePath / httpsCertFilePath — file-path TLS client cert and key; Nub takes inline PEM only.
• Per-host networkSettings proxies — the proxy Nub applies is process-wide, not per registry host.
• nodeLinker: pnp — PnP install generation is out of scope; install with Yarn, run with Nub.