Manifest (package.json)
Manifest files (also called package.json because of their name) contain everything needed to describe the settings unique to one particular package. Project will contain multiple such manifests if they use the workspace feature, as each workspace is described through its own manifest. Note that defaults for these fields can be set via the initFields settings.
name
Name of the package.
Used to identify it across the application, especially amongst multiple workspaces. The first part of the name (here @scope/) is optional and is used as a namespace).
version
Version of the package.
Usually doesn't have any impact on your project, except when it is a workspace - then its version must match the specified ranges for the workspace to be selected as resolution candidate.
packageManager
Define the package manager that should be used when working on this project.
This field is used by Corepack and similar tools to detect the Yarn version in use in a project - in a sense, it has the same purpose as your lockfile, but only for Yarn itself.
Yarn will automatically set this value when running yarn set version.
type
Define how should be interpreted .js files.
A Node.js v13.x option. Possible values are commonjs (the default) and module. Yarn 3+ will generate a .pnp.cjs file when using PnP regardless of this option.
private
Define whether the package is meant to be published.
If true, the package is considered private and Yarn will refuse to publish it regardless of the circumstances.
license
SPDX identifier defining the license under which the package is distributed.
os
Set of platforms on which this package works.
The value of process.platform() will be compared at install-time against this set. Should no matches be found, any postinstall script the package define will be skipped. If the package was exclusively depended upon via optionalDependencies entries, the package won't be installed at all.
cpu
Set of CPU architectures on which this package works.
The value of process.arch() will be compared at install-time against this set. Should no matches be found, any postinstall script the package define will be skipped. If the package was exclusively depended upon via optionalDependencies entries, the package won't be installed at all.
libc
Set of C standard libraries on which this package depends.
The host standard library will be compared at install-time against this set. Should no matches be found, any postinstall script the package define will be skipped. If the package was exclusively depended upon via optionalDependencies entries, the package won't be installed at all.
main
Path of the file that should be resolved when requiring the package via a bare identifier.
This field can be modified at publish-time through the use of the publishConfig.main field.
module
Path of the file that should be resolved when requiring the package via a bare identifier in an ES6-compatible bundler environment.
This field should be considered deprecated, with exports being its official replacement.
languageName
Arbitrary value selecting the linker to use when installing the dependency.
This is an internal package setting that shouldn't be touched unless you really know what you're doing.
bin
Set of files to expose via yarn run bin-name and the shell environment.
If set to a string, the binary value will be the package name (not including its scope part).
scripts
Set of scripts to expose via yarn run script-name, or as lifecycle hooks.
Scripts in Yarn are executed by a POSIX-like shell which implements most features you would want to use in one-liner scripts. For example you can assign environment variables using the POSIX syntax, and Yarn will make it work across both Linux, OSX, and Windows.
dependencies
Set of dependencies that must be made available to the current package in order for it to work properly.
Consult the protocol documentation for more information.
optionalDependencies
Set of dependencies that Yarn should only try to install if the os/cpu/libc fields match those of the host platform.
Unlike regular dependencies, those listed in optionalDependencies are allowed to have a failing postinstall step - in fact, they won't even be installed at all if the os/cpu/libc filters don't cover the host platform.
Note that optionalDependencies only cares about whether the package should install/build or not - it should still be resolvable, as otherwise it's impossible to tell whether a failure to retrieve the package metadata is intentional or not.
devDependencies
Set of dependencies that must be made available to the current package in order for it to work properly as a workspace.
Unlike regular dependencies, those listed in devDependencies will only be required when the package is installed as part of a workspace project - usually by cloning the project repository then running yarn install inside it.
peerDependencies
Set of dependencies that the package must inherit from its ancestor in the dependency tree.
The semantic of peer dependencies guarantee that when the package require the dependency, it will be returned the exact same object instance as the one that would be returned to the package's ancestor. This mechanism makes peer dependencies the best way to share singleton states across multiple packages.
As an extension, Yarn supports "peer dependencies with default": dependencies listed in both the dependencies and a peerDependencies fields will try to solve the peer dependency first, but will fallback to the regular dependency if it can't be satisfied otherwise.
workspaces
Array of folder glob patterns referencing the workspaces of the project.
Workspaces are an optional feature used by monorepos to split a large project into semi-independent subprojects, each one listing their own set of dependencies. The workspaces field is a list of glob patterns that match all directories that should become workspaces of your application. Consult the workspaces documentation for more information.
dependenciesMeta
Extra settings affecting how the dependencies and devDependencies fields are interpreted.
In the context of a workspaced project most of these settings will affect all workspaces and as such must be specified at the root of the project. Unless noted otherwise, the dependenciesMeta field will be ignored if found within a workspace.
dependenciesMeta.built
Define whether to run the postinstall script or not.
If false, the package will never be built (deny-list). This behavior is reversed when the enableScripts yarnrc setting is toggled off - when that happens, only packages with built explicitly set to true will be built (allow-list); as for those with built explicitly set to false, they will simply see their build script warnings downgraded into simple notices.
dependenciesMeta.optional
Define whether the dependency is optional or not.
Unlike most other settings in dependenciesMeta, optional is allowed anywhere in the dependency tree. It has the exact same effect as optionalDependencies - in fact, that's internally what optionalDependencies compiles down to.
dependenciesMeta.unplugged
Define whether the package must be unplugged or not.
If true, the specified package will be automatically unplugged at install time. This should only be needed for packages that contain scripts in other languages than Javascript (for example nan contains C++ headers).
peerDependenciesMeta
Extra settings affecting how the peerDependencies field is interpreted.
Unlike dependenciesMeta, peerDependenciesMeta is allowed in any parts of the dependency tree.
peerDependenciesMeta.optional
Define whether to log a warning when the peer dependency can't be satisfied.
If true, the selected peer dependency will be marked as optional by the package manager, silencing any warning we would otherwise emit.
resolutions
Override the resolutions of specific dependencies.
This field allows you to instruct Yarn to use a specific resolution (specific package version) instead of anything the resolver would normally pick. This is useful to enforce all your packages to use a single version of a dependency, or backport a fix. The syntax for the resolution key accepts one level of specificity, so all the following examples are correct.
Note: When a path is relative, like it can be with the file: and portal: protocols, it is resolved relative to the path of the project.
Note: The resolutions field can only be set at the root of the project, and will generate a warning if used in any other workspace.
preferUnplugged
Define whether the package must be unplugged or not.
While Yarn attempts to reference and load packages directly from their zip archives, it may not always be possible. A heuristic tries to detect cases where zip-loading would be problematic and unpack the files on disk instead but, being just a heuristic, it may report incorrect results.
The preferUnplugged field lets you define yourself, as a package author, whether your package works or not when stored as an archive. If set, it will override the default heuristic.
files
Array of file glob patterns that will be included within the published tarball.
File patterns follow a similar syntax to .gitignore, but reversed: including a file, directory, or glob pattern (*, **/*, and such) will make it so that file is included in the tarball when it’s packed. Omitting the field will make it default to ["*"], which means it will include all files.
If this field is missing, Yarn will use the project's .gitignore to generate the pack list, or the .npmignore file instead if available.
Some special files and directories are also included or excluded regardless of whether they exist in the files array.
publishConfig
Extra settings affecting how the package is published.
publishConfig.access
Define the access to use when publishing the package.
Valid values are public and restricted, but restricted usually requires to register for a paid plan (this is up to the registry you use).
publishConfig.bin
Replacement of the package's bin field, used in the published tarball over the main one.
publishConfig.browser
Replacement of the package's browser field, used in the published tarball over the main one.
publishConfig.executableFiles
Set of files that must be marked as executable (+x) in the published tarball.
publishConfig.main
Replacement of the package's main field, used in the published tarball over the main one.
publishConfig.module
Replacement of the package's module field, used in the published tarball over the main one.
publishConfig.registry
If present, will replace whatever registry is defined in the configuration when the package is about to be pushed to a remote location.
publishConfig.type
Replacement of the package's type field, used in the published tarball over the main one.
installConfig
Extra settings affecting how the package is installed.
installConfig.hoistingLimits
Defines the highest point where packages can be hoisted.
See nmHoistingLimits for more information.
installConfig.selfReferences
Defines whether workspaces are allowed to require themselves.
See nmSelfReferences for more information.