@yarnpkg/doctor

@yarnpkg/doctor

A cli tool to help package maintainers support pnp.

Usage

To check your package run:

yarn dlx @yarnpkg/doctor ./package-dir

You'll get a pretty output with all the warnings.

Rules

• no unlisted dependencies
• no unmet peer dependencies
• no node_module strings
• no unqualified webpack loaders
• no bundleDependencies

no unlisted dependencies

This rule warns when imported dependencies are not listed in a project/workspace's package.json.

Node allows you to import any package without having a version specified in your package.json. This can lead to subtle and hard to solve bugs.

For example:

1. Node might find a globally installed package and the project works on your machine. While other your colleagues might be missing the globally installed package or (worse) have an incompatible version installed.

2. Or Node might find a transitive dependency (dependency of a dependency) and use that. If you remove or upgrade that dependency and it affects the transitive dependency then it can trigger all sorts of bugs.

By making sure all dependencies are listed in the package.json pnp can make your project less brittle.

no unmet peer dependencies

This rule warns when a package has unmet peer dependencies.

Peer dependencies are useful for allowing package authors to delegate control of a dependency's version to the package user. When used correctly they prevent version conflicts and reduce bundle sizes.

Peer dependencies must be manually added to the package user's package.json. Because they responsibility of the package user they can be overlooked.

This rule ensures that all peer dependencies are included and therefore installed for your project.

no node module strings

This rule warns when node_modules appears in strings or template literals.

If a string literal includes "node_modules" else it is likely a sign that the package is doing shady things with node_modules which would likely fail under PnP.

One of the big benefits of Plug-n-Play is that it does away with node_modules directories to achieve zero installs, increased stability and reliability. Therefore, resolutions that rely on the presence of a node_modules folder will fail.

Aside from satisfying Plug'n'Play requirements, resolving packages using node_modules this way is brittle and may result unpredictable packages versions and subtle bugs.

Examples of incorrect code for this rule:

var module = require("../node_modules/lodash");

Examples of correct code for this rule:

var foo = require("lodash"); // importing a module by its name

no unqualified webpack config

This rule disallows referencing loaders or plugins in string literals in a webpack.config.js in a non-private package.

Ensures that third party tools (CRA, Next, Vue-cli, etc) resolve their own versions of loaders and presets.

When loaders and plugins are included as strings e.g loader: 'file-loader' in a webpack.config.js then Webpack will try to resolve it from the point of view of the project root.

If the webpack config is located in a dependency, as with tools such as Create-React-App, Next.js and Gatsby, then Webpack might accidentally use an different hoisted version of a plugin. This can cause various weird bugs and crashes.

The third party tool should use require.resolve('file-loader') so that Webpack loads the plugin through an absolute path and it will use the loader/plugin it specifies in its own package.json.

Examples of incorrect code for this rule:

const webpackConfig = {
  use: `ts-loader`,
};

Examples of correct code for this rule:

const webpackConfig = {
  use: require.resolve(`ts-loader`),
};

This rule is a temporary measure to address this issue

no bundleDependencies

This rule warns when the bundleDependencies (or bundledDependencies) field is used.

Visit the dedicated section on the website to learn more.

Further reading

• Yarn 2 docs
• Introduction to plug-n-play

Changelog

4.0.0

Major Changes

• With Node.js 16's now being End of Life'd, we dropped support for Node.js versions lower than 18.12.

• Some important defaults have changed:

  • yarn init and yarn set version will prefer using packageManager rather than yarnPath when possible (when they detect COREPACK_ROOT in your environment variables).

  • yarn init will no longer use zero-install by default. You still can enable it, but it should make it easier to start one-of projects without having to rewrite the configuration afterwards.

    • As a result, enableGlobalCache now defaults to true. If your project uses Zero-Installs, the first yarn install you run after migrating to 4.0 will automatically set enableGlobalCache: false in your local .yarnrc.yml.

  • yarn workspaces foreach now requires one of --all, --recursive, --since, or --worktree to be explicitly specified; the previous default was --worktree, but it was rarely what users expected.

  • compressionLevel now defaults to 0 rather than mixed. It's been proved significantly faster on installs, and the size impact was reasonable enough to change the default. Note that it benefits you even if you use Zero-Installs: as per our tests, a zero-compression is actually easier to handle for Git (you can see by yourself with those examples using compressionLevel: 0 vs compressionLevel: mixed).

    • To avoid making the upgrade too disruptive, Yarn will check whether Zero-Installs are enabled the first time you run yarn install after migrating from 3.6 to 4.0. If you do, it will automatically set the old default (compressionLevel: mixed) in your .yarnrc.yml file. You can then remove it whenever you feel ready to actually change the compression settings.

• All official Yarn plugins are now included by default in the bundle we provide. You no longer need to run yarn plugin import for official plugins (you still need to do it for third-party plugins, of course).

  • This doesn't change anything to the plugin API we provide, which will keep being maintained.
  • Yarn still has a modular architecture and uses the exact same APIs as contrib plugins; all that changes is how we distribute our own features.

• Yarn's UI during installs has been greatly improved:

  • Packages added and removed from the lockfile are now explicitly reported.
  • Fluctuations in the project cache size are now reported as a single line.
  • Unactionable warnings (node-gyp and transitive peer dependency errors) have been removed.
  • Skipped builds are now only reported during initial installs and manual yarn rebuild calls.
  • The Yarn version is now displayed on installs to help us investigate issues when reported as screenshots.
  • Deprecation checks have been moved to yarn npm audit.

• Some settings were renamed or removed:

  • caFilePath is now httpsCaFilePath
  • preferAggregateCacheInfo has been removed (it's now always on)
  • pnpDataPath has been removed to adhere to our new PnP specification. For consistency, all PnP files will now be hardcoded to a single value so that third-party tools can implement the PnP specification without relying on the Yarn configuration.

• The yarn npm audit command has been reimplemented:

  • The audit registry must now implement the /-/npm/v1/security/advisories/bulk endpoint.
  • The npmAuditRegistry can be used to temporarily route audit queries to the npm registry.
  • Deprecations are now returned by default. To silence them, use yarn npm audit ! --no-deprecations.

• Some legacy layers have been sunset:

  • Plugins cannot access the Clipanion 2 APIs anymore (upgrade to Clipanion 3)
  • Plugins cannot access the internal copy of Yup anymore (use Typanion instead)
  • Yarn will no longer remove the old Yarn 2.x .pnp.js file when migrating.
  • The --assume-fresh-project flag of yarn init has been removed.

API Changes

The following changes only affect people writing Yarn plugins:

• The ZipFS and ZipOpenFS classes have been moved from @yarnpkg/fslib to @yarnpkg/libzip. They no longer need or accept the libzip parameter.

  • Reading the zip archives is now done on the Node.js side for performance; as a result, the open, ZIP_CREATE, and ZIP_TRUNCATE bindings are no longer needed for ZipFS and have also been removed.

• The dependencies field sent returned by Resolver#resolve must now be the result of a Configuration#normalizeDependencyMap call. This change is prompted by a refactoring of how default protocols (ie npm:) are injected into descriptors. The previous implementation caused various descriptors to never be normalized, which made it difficult to know what were the descriptors each function should expect.

  • Similarly, the descriptors returned by Resolve#getResolutionDependencies are now expected to be the result of Configuration#normalizeDependency calls.

  • Note that this only applies to the dependencies field; the peerDependencies field is unchanged, as it must only contains semver ranges without any protocol (with an exception for workspace:, but that's not relevant here).

• The Resolve#getResolutionDependencies function must now return an object of arbitrary string keys and descriptor values (instead of a map with DescriptorHash keys). Those descriptors will be resolved and assigned to the same keys as the initial object. This change allows resolvers to wrap resolution dependencies from other resolvers, which wasn't possible before since it'd have caused the key to change.

• The generateLoader function in @yarnpkg/pnp no longer generates the $$SETUP_STATE function, it now needs to be present in the loader passed to the function.

• The getCustomDataKey function in Installer from @yarnpkg/core has been moved to Linker.

• renderForm's options argument is now required to enforce that custom streams are always specified.

• npmConfigUtils.getAuditRegistry no longer takes a Manifest as its first argument.

• The FetchOptions.skipIntegrityCheck option has been removed. Use FetchOptions.cacheOptions.skipIntegrityCheck instead.

• MapConfigurationValue has been removed. Use miscUtils.ToMapValue instead.

• Manifest.isManifestFieldCompatible and Manifest.prototype.isCompatibleWith{OS,CPU} have been removed. Use Manifest.prototype.getConditions and structUtils.isPackageCompatible instead.

• versionUtils.{fetchBase,fetchRoot,fetchChangedFiles} have been moved from @yarnpkg/plugin-version to @yarnpkg/plugin-git. Use gitUtils.{fetchBase,fetchRoot,fetchChangedFiles} instead.

• For consistency reasons:

  • Link{Resolver,Fetcher} have been renamed to Portal{Resolver,Fetcher}
  • RawLink{Resolver,Fetcher} have been renamed to Link{Resolver,Fetcher}

• FakeFS classes are now required to implement lutimes{Sync,Promise}.

• workspace.dependencies has been removed. Use workspace.anchoredPackage.dependencies instead.

• The Installer class must now return BuildRequest structures instead of BuildDirective[]. This lets you mark that the build must be skipped, and the reason why.

• startCacheReport has been removed, and is now part of the output generated by fetchEverything.

• forgettableNames & forgettableBufferSize have been removed (the only messages using them have been removed, making the forgettable logs implementation obsolete).

• workspace.locator has been removed. You can instead use:

  • workspace.anchoredLocator to get the locator that's used throughout the dependency tree.
  • workspace.manifest.version to get the workspace version.

• configuration.{packageExtensions,refreshPackageExtensions} have been removed. Use configuration.getPackageExtensions instead.

• configuration.normalizePackage now requires a packageExtensions option.

• ProjectLookup has been removed. Both Configuration.find and Configuration.findProjectCwd now always do a lockfile lookup.

Installs

• Yarn now caches npm version metadata, leading to faster resolution steps and decreased network data usage.
• The pnpm linker avoids creating symlinks that lead to loops on the file system, by moving them higher up in the directory structure.
• The pnpm linker no longer reports duplicate "incompatible virtual" warnings.

Features

• enableOfflineMode is a new setting that, when set, will instruct Yarn to only use the metadata and archives already stored on the local machine rather than download them from the registry. This can be useful when performing local development under network-constrained environments (trains, planes, ...).
• yarn run bin now injects the environment variables defined in .env.yarn when spawning a process. This can be configured using the injectEnvironmentFiles variable.
• yarn workspaces foreach now automatically enables the yarn workspaces foreach ! --verbose flag in interactive terminals.
• Constraints can now be written in JavaScript. See the revamped documentation for more information.

Bugfixes

• yarn dlx will no longer report false-positive UNUSED_PACKAGE_EXTENSION warnings
• yarn workspace will now set $INIT_CWD to the CLI working directory rather than the workspace root.

Shell

• The builtin shell now supports whitespace-only commands.

Compatibility

• The patched filesystem now supports FileHandle.readLines.
• PnP now reports missing files when in watch mode.