yarnpkg/berry
github.com/yarnpkg/berry ↗ · 1581 files · 12.0 MB
Fast, reliable, and secure dependency management.
Overview
Berry is Yarn’s TypeScript package-manager monorepo, serving JavaScript developers, workspace maintainers, and tooling authors through both a CLI and reusable libraries. Its core manages dependency graphs, caches, installation state, and scripts, while plugins supply package protocols, commands, and filesystem installation strategies. The inspected implementation supports Plug’n’Play, node_modules, and pnpm-style linking, with a separate React/Docusaurus documentation application.
System map
The repository separates command dispatch, project management, protocol integrations, and filesystem installation. The CLI composes plugins around reusable core classes rather than containing the dependency engine itself. Distribution includes generated CLI bundles and published library packages, while documentation has its own application and build configuration.
- The root package is a private packages/* workspace monorepo; it declares Jest, ESLint, and TypeScript scripts and pins packageManager to Yarn 4.2.1.
- The executable source entrypoint imports polyfills and calls runExit with argv, portable cwd, its own path, and getPluginConfiguration().
- lib.ts owns Clipanion context, Node >=18.12.0 validation, yarnPath delegation, plugin command registration, exit-code handling, and temporary-directory cleanup.
- Core exposes Configuration, Project, Workspace, Cache, and Manifest; Project.find initializes resolutions and workspaces and uses linker lookup when cwd belongs to an installed package.
- Plugin contributions are typed as configuration, commands, fetchers, linkers, resolvers, and hooks; the CLI’s standard bundle includes npm, JSR, constraints, linking, and workspace plugins.
- Filesystem installation has distinct implementations: PnpLinker generates loader/data files, NodeModulesLinker persists a package tree, and plugin-pnpm registers PnpmLinker with a configurable store.
- build:cli invokes builder build bundle, which bundles sources/cli.ts into bundles/yarn.js using esbuild; the manual release workflow builds binaries, pushes tags, and invokes release publishing scripts.
- The separate Docusaurus workspace uses React 19 and provides development/build scripts; its configuration generates CLI and TypeDoc API documentation alongside docs and blog routes.
Feature catalog
The inspected command registries cover dependency editing, installation, execution, diagnostics, workspace operations, and registry publishing. Protocol and linker plugins provide alternative dependency sources and installation layouts. Additional plugins support constraints, release workflows, patching, project creation, and editor tooling; this catalog groups the evidenced surfaces rather than asserting exhaustive inspection of every command implementation.
- plugin-essentials registers add, remove, up, dedupe, install, rebuild, cache clean, resolution overrides, and package link/unlink commands.
- Execution features include run, exec, and node; RunCommand supports top-level selection, binaries-only mode, Node --require forwarding, and a unique colon-named script fallback across workspaces.
- Workspace features include listing and selecting a workspace, plus workspaces focus and foreach supplied by plugin-workspace-tools.
- Installation supports PnP loader generation, a persisted node_modules tree, and a pnpm-style store; install also exposes immutable, immutable-cache, check-cache, refresh-lockfile, and execution modes.
- Documented dependency integrations include npm semver, file, Git, GitHub, HTTP tarballs, exec, link, portal, and patch protocols; JSR adds its own resolver/fetcher and converts jsr: dependencies when packing.
- npm CLI commands include audit, info, login/logout, publish, whoami, dist-tag management, and staged-publication approve/list/reject; publication provenance is a configurable option.
- Constraints provide check/query/source commands and optional install-time checking; version provides apply/check/version with deferred records, while documented plugins add dlx, init, interactive upgrades, pack, patch, stage, and TypeScript assistance.
- User diagnostics and tooling include config get/set/unset, explain and peer-requirement explanation, info, why, plugin management, Yarn version selection, PnPify, editor SDK generation, and a documentation site with CLI/configuration/API navigation.
Data flow
Inputs enter through argv, environment settings, RC files, package manifests, and registry metadata. Configuration and Project own the interpreted settings and dependency graph, while fetchers translate package identities into filesystem-backed artifacts. Linkers publish runtime layouts, and lockfiles plus compressed installation state support subsequent commands.
- argv becomes a Clipanion command after startup configuration and cwd handling; command context carries cwd, plugin configuration, and stdin/stdout/stderr.
- Configuration.find combines environment settings, discovered RC files, and a home RC file; it processes yarnPath fields before project discovery and plugin activation.
- Workspace.setup loads a manifest, derives stable workspace descriptors/locators from relative paths, expands workspace patterns, excludes node_modules/.git/.yarn, and sorts discovered paths.
- Descriptor resolution first resolves resolver-specific dependencies, requests candidates, selects the first candidate, optionally verifies it with getSatisfying, and records descriptor-to-locator hashes.
- NpmSemverResolver turns registry versions into approved, preferably nondeprecated candidates sorted descending; unconventional tarball URLs are bound into locators, and resolve loads manifest dependency metadata.
- NpmSemverFetcher requests a checksum-aware cached package; a miss downloads a tarball and converts it into a vendor-prefixed ZIP, returning packageFs, releaseFs, prefixPath, and checksum.
- fetchEverything updates storedChecksums and releases fetched filesystems; linkEverything creates installers with restored custom data, attaches internal/external relationships, and captures finalizeInstall custom data and build records.
- Project.persist writes the normalized lockfile and workspace manifests; installation state is V8-serialized and gzipped, while restoration only reuses saved resolutions when the lockfile checksum matches.
Behavior traces
Three concrete flows were followed through their implementation: CLI startup, installation through persistence, and script/binary execution. Startup can terminate by handing control to another Yarn executable. Installation and execution both restore project state, but apply different resolution, linking, and subprocess branches.
- Startup: cli.ts calls getPluginConfiguration(), which reads the standard bundle list and constructs modules/plugins; runExit then calls getBaseCli() and run().
- Startup dispatch: run() performs validateNodejsVersion → getCoreConfiguration → optional runYarnPath; otherwise checkCwd → initTelemetry → initCommands → cli.process → cli.run. Delegation sets YARN_IGNORE_PATH=1 in the child.
- Install setup: InstallCommand.execute finds Project, applies applicable lockfile migration settings, finds Cache, requires a workspace, restores state without resolutions, and derives refresh/check behavior from explicit flags or hardened mode before Project.install.
- Install resolution: Project.install runs validateProject, stops on validation errors, snapshots an immutable lockfile, invokes resolveEverything, emits peer warnings, and rejects changed generated lockfile content before fetching.
- Install persistence: fetchEverything → optional persist → linkEverything → persistInstallStateFile → post-install validation. UpdateLockfile mode fetches only missing checksums and skips linking; SkipBuild returns from linking before package builds.
- Run script: RunCommand.execute calls Configuration.find → Project.find → restoreInstallState → hasPackageScript → executePackageScript; initialization creates a temporary binary environment, then wrapScriptExecution wraps portable-shell execution.
- Run fallback: absent a selected script, RunCommand checks dependency binaries and forwards Node flags; otherwise it accepts one matching colon-named workspace script. Binary execution chooses Node or direct pipevp and removes its binary folder in finally.
- State recovery: restoreInstallState reads and gunzips the saved file, deserializes it, and restores requested categories. When resolution restoration is requested, unreadable state or a changed lockfile triggers applyLightResolution → resolveEverything(lockfileOnly) → persistInstallStateFile.
Testing signals
Tests and CI were inspected, not executed; their existence is not a passing result. The sampled Jest suites exercise project recovery, configuration handling, installation modes, execution precedence, and mocked network behavior. CI defines broader platform and ecosystem checks, but this bounded investigation does not establish exhaustive coverage or current CI status.
- Root test:unit uses Jest 29; its Node environment applies a custom JavaScript/TypeScript transformer and polyfills, excludes acceptance-tests and plugin-compat, and sets a 50-second timeout.
- Acceptance tests have a separate Jest configuration and setup; beforeEach starts the package server and initializes the fixture registry, and test:integration delegates to test:unit with that configuration.
- Project.test.ts asserts Manifest.raw updates, preservation of resolver-specific dependencies during lockfile-only resolution, and recovery after replacing installation state with invalid content.
- Configuration.test.ts checks hideSecrets redaction for both top-level npmAuthToken and scoped tokens; this directly tests formatted access rather than every logging or subprocess exposure path.
- Install acceptance assertions cover inline build logs, SkipBuild suppression without changing PnP artifacts, and immutable refusal to create or alter a lockfile; the inspected ZIP-symlink case excludes Windows.
- Run acceptance tests cover invocation with and without run, script exit-code propagation, delegated yarnPath exit codes, dependency binary execution, and script precedence over binaries.
- The inspected HTTP tests intercept requests through hooks: core checks wrapper arguments, while npm checks registry URL joining and noninteractive OTP failure. These tests do not themselves exercise real TLS, proxies, or live registry authentication.
- Integration CI defines immutable/cache checks and sharded unit/acceptance jobs across Linux, Windows, and macOS; scheduled ecosystem workflows add compatibility checks, but the Webpack thread-loader case immediately exits and is not exercised.
Risk map
These are security-sensitive source observations and one explicitly labeled review hypothesis, not confirmed vulnerabilities. The main boundaries involve dynamic code, inherited environments, authenticated network requests, archive integrity, and filesystem mutation. Persistence ordering and a documented symlink uncertainty also warrant care when changing critical flows.
- Dynamic plugin loading executes dynamicRequire(pluginPath) and factory(pluginRequire); builtin modules remain available. Missing HTTP-sourced plugins are downloaded and written locally, with checksum enforcement conditional on a configured checksum.
- Package lifecycle scripts can execute preinstall/install/postinstall or synthesized node-gyp rebuild; soft links, built metadata, enableScripts, and architecture gate these builds, while explicit run executes selected scripts through the shell.
- Configuration reads a home RC file and configured environment files outside the immediate project boundary; makeScriptEnv copies the resulting environment into subprocess environments and prepends temporary wrappers to PATH.
- Network policy is configurable: unsafe HTTP requires a hostname whitelist, enableNetwork can block requests, enableStrictSsl controls certificate rejection, and optional CA/certificate/key paths are read. npm authentication may supply hook headers, bearer tokens, Basic credentials, or OIDC tokens.
- Archive mismatch handling depends on checksumBehavior: ignore preserves the expected hash, update accepts the actual hash, reset rejects the cached entry, and throw errors; check-cache overrides mismatch handling to throw, while linking requests skipIntegrityCheck.
- Installation persists manifests/lockfile before linking and saves state before post-install validation; PnP finalization can remove detected node_modules or obsolete loader/unplugged artifacts, so failures can follow filesystem changes.
- initializeWorkspaceEnvironment realpaths package.json to choose default cwd; its source comment explicitly says tests for that behavior are absent and the historical symlink use case is uncertain. This is a documented local coverage concern.
- Review hypothesis: Smart merge crosses a consequential artifact trust boundary because pull_request_target checks out the PR head to generate a patch, then a separate job applies that artifact and pushes using a bot token. Exploitability was not assessed. (inferred)
Extension points
The Plugin type is the primary extension contract, with factories assembling runtime integrations. Typed configuration augmentation and ordered hooks allow cross-cutting behavior without expanding command implementations. Build profiles, shell builtins, and documentation plugins provide additional extension surfaces.
- A Plugin can contribute configuration, command classes, fetchers, linkers, resolvers, and hooks; plugin-constraints demonstrates ConfigurationValueMap augmentation with typed settings and defaults.
- CLI commands plug into each plugin’s commands array; initCommands iterates activated plugins and registers every contributed class with Clipanion.
- Configuration.makeResolver constructs plugin resolver instances behind VirtualResolver and WorkspaceResolver; NpmSemverResolver demonstrates supportsDescriptor/supportsLocator, candidate selection, satisfying checks, and metadata resolution.
- Configuration.makeFetcher composes builtin virtual/workspace fetchers with plugin fetchers; NpmSemverFetcher shows the cache loader pattern and filesystem/release/checksum result contract.
- New installation layouts implement Linker package/location lookup and makeInstaller; Installer separates installPackage, dependency attachment, finalization, retained fetch lifetimes, and migratable custom state.
- Hooks can modify script environments, wrap script/network execution, reduce dependency descriptors, and validate installs; triggerHook and reduceHook await contributors sequentially in plugin iteration order.
- Builder supports additional --plugin entries and named profiles; findPlugins accepts profile combinations separated by '+', validates them against manifest bundles, and deduplicates contributions.
- The portable shell accepts custom builtins, filesystem, environment, variables, and glob behavior; documentation extends separately through remark plugins, generated CLI docs, and TypeDoc entries discovered from package exports.
Contributor handoff
Begin with the relevant command, its core operation, and the owning plugin instead of treating this as a React application. Preserve generated-artifact boundaries, typed portable paths, and repository constraint conventions. Tests and CI were inspected, not executed; proposed checks below require separate execution authority, and the inventory remains bounded.
- Read the root and CLI manifests first: CLI version 4.18.1 differs from the root packageManager pin of Yarn 4.2.1, and standard plugin membership is declared in the CLI manifest.
- For installation changes, read InstallCommand and Project.install together; the command’s source explicitly directs reusable install customization into configuration/core because other commands also install projects.
- For protocol changes, keep NpmSemverResolver.getCandidates and getSatisfying consistent: both use selectMatchingVersions, whose prerelease fallback applies only to a literal '*' with no stable matches.
- For linker changes, honor Installer ordering and fetch-result ownership; custom data must tolerate absence and handle its own migration, and asynchronous holds require bounded concurrency.
- Follow strict TypeScript and the portable-path conversions already used by Workspace; ESLint requires semverUtils.validRange and httpUtils instead of direct semver.Range/validRange and global fetch.
- Dependency edits must account for yarn.config.cjs constraints: internal dependencies become workspace:^, most shared ranges are synchronized, lodash/inquirer are forbidden, and package metadata/prepack conventions are enforced.
- Edit source implementations rather than generated bundles, hooks, workers, and grammars; ESLint excludes those outputs, while CI conditionally regenerates PnP hooks and checks their diffs.
- Tests and CI were inspected, not executed. For later authorized validation, start with the affected Jest file or acceptance command suite using test:unit/test:integration, then use existing test:lint and typecheck:all scripts; mocked transport tests and explicitly skipped compatibility cases limit conclusions.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 511 | 59% |
| JavaScript | 341 | 39% |
| JSON | 250 | docs/config |
| Markdown | 104 | docs/config |
| YAML | 42 | docs/config |
| Shell | 13 | 1% |
| CSS | 10 | docs/config |
| C | 2 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1454 files)
Source layout — packages/
| Path | Files |
|---|---|
packages/acceptance-tests/ | 153 |
packages/plugin-npm-cli/ | 17 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 1454 |
scripts/ | 45 |
.github/ | 41 |
.yarn/ | 16 |
.vim/ | 1 |
Docs found: CONTRIBUTING.mdLICENSE.mdREADME.md
Package
package.json — @yarnpkg/monorepo, 24 declared dependencies.
@arcanis/sherlock@eslint/config-inspector@iarna/toml@types/jest@types/micromatch@types/node@types/semver@yarnpkg/cli@yarnpkg/core@yarnpkg/eslint-config@yarnpkg/fslib@yarnpkg/libzip
CI & config entrypoints
README.md— Repository readme.github/workflows/e2e-gulp-workflow.yml— GitHub Actions workflow.github/workflows/e2e-svelte-kit-workflow.yml— GitHub Actions workflow.github/workflows/e2e-nm-berry-workflow.yml— GitHub Actions workflow.github/workflows/pr-smart-merge.yml— GitHub Actions workflow.github/workflows/e2e-fsevents-workflow.yml— GitHub Actions workflow.github/workflows/e2e-storybook-workflow.yml— GitHub Actions workflow.github/workflows/release-branch.yml— GitHub Actions workflow.github/workflows/e2e-webpack-workflow.yml— GitHub Actions workflow.github/workflows/e2e-vitest-workflow.yml— GitHub Actions workflow
Structural health signals
Average score 6.8/10 across 96 analyzed source files; 36 hotspots surfaced.
packages/plugin-nm/sources/NodeModulesLinker.ts— 1217 lines, score 4 (Large file, Deep nesting)packages/yarnpkg-pnp/sources/loader/makeApi.ts— 1027 lines, score 4 (Large file, Deep nesting)packages/acceptance-tests/pkg-tests-specs/sources/pnp.test.js— 2285 lines, score 4.7 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
e4e423a1eb112026-09-24 — Sync master with the changes from master75ebe063092f2026-09-24 — Releasing 2 new packages8b6cf965c4a02026-09-24 — Update Yarn version configuration for @yarnpkg/cli502acfec2f4b2026-09-19 — fix(core): patch got to prevent crash on settled promise cancelation (#7249)57081c05a3982026-07-29 — Sync master with the changes from master