Important: This documentation covers modern versions of Yarn.
For 1.x docs, see classic.yarnpkg.com.
Yarn
Manifestspackage.jsonYarnrc files.yarnrc.yml

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

The 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).

"name": "@scope/name",

version

The 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.

"version": "1.2.3",

type

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.

"type": "commonjs",

private

If true, the package is considered private and Yarn will refuse to publish it regardless of the circumstances. Setting this flag also unlocks some features that wouldn't make sense in published packages, such as workspaces.

"private": true,

license

An SPDX identifier that indicates under which license is your package distributed.

"license": "MIT",

os

A value compared during install with process.platform. If the values don't match, the package won't see its postinstall scripts run (if listed in dependencies) or won't be installed at all (if listed in optionalDependencies).

"os": [
"linux",
"darwin",
"win32",
],

cpu

A value compared during install with process.arch. If the values don't match, the package won't see its postinstall scripts run (if listed in dependencies) or won't be installed at all (if listed in optionalDependencies).

"cpu": [
"x64",
"ia32",
"arm64",
],

libc

A value compared during install with the host standard C library. If the values don't match, the package won't see its postinstall scripts run (if listed in dependencies) or won't be installed at all (if listed in optionalDependencies).

"libc": [
"glibc",
"musl",
],

main

The path that will be used to resolve the qualified path to use when accessing the package by its name. This field can be modified at publish-time through the use of the publishConfig.main field.

"main": "./sources/index.js",

module

The path that will be used when an ES6-compatible environment will try to access the package by its name. Doesn't have any direct effect on Yarn itself.

"module": "./sources/index.mjs",

languageName

An enumeration used by the linker plugins to figure which linker should install a specific package. Only some values are allowed, consult the documentation to know more.

"languageName": "node",

bin

A field used to expose some executable Javascript files to the parent package. Any entry listed here will be made available through the $PATH. Note that it is very advised to only expose Javascript files for portability reasons (shellscripts and non-js binaries require the user to have a specific shell, and are incompatible with zip access).

"bin": {
"my-bin": "./dist/my-bin.js",
},

scripts

A field used to list small shell scripts that will be executed when running yarn run. Scripts are by default executed by a miniature shell, so some advanced features might not be available (if you have more complex needs, we recommend you to just execute a Javascript file). Note that scripts containing : (the colon character) are globals to your project and can be called regardless of your current workspace. Finally, be aware that scripts are always executed relative to the closest workspace (never the cwd).

"scripts": {
"test": "jest",
"build": "webpack-cli --config ./webpack.config.js",
"count-words": "echo \"$@\" | wc -w",
},

dependencies

The set of dependencies that must be made available to the current package in order for it to work properly. Consult the list of supported ranges for more information.

"dependencies": {
"webpack": "^5.0.0",
},

optionalDependencies

Similar to the dependencies field, except that these entries will not be required to build properly should they have any build script. Note that such dependencies must always be resolvable (otherwise we couldn't store it in the lockfile, which could lead to non-reproducible installs), but those which list os / cpu / libc fields will not be fetched unless they match the current system architecture.

This field is usually not what you're looking for, unless you depend on the fsevents package. If you need a package to be required only when a specific feature is used then use an optional peer dependency. Your users will have to satisfy it should they use the feature, but it won't cause the build errors to be silently swallowed when the feature is needed.

"optionalDependencies": {
"fsevents": "^5.0.0",
},

devDependencies

Similar to the dependencies field, except that these dependencies are only installed on local installs and will never be installed by the consumers of your package.

"devDependencies": {
"webpack": "^5.0.0",
},

peerDependencies

Peer dependencies are inherited dependencies - the consumer of your package will be tasked to provide them. This is typically what you want when writing plugins, for example. Note that peer dependencies can also be listed as regular dependencies; in this case, Yarn will use the package provided by the ancestors if possible, but will fallback to the regular dependencies otherwise.

"peerDependencies": {
"react": "*",
"react-dom": "*",
},

workspaces

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.

"workspaces": [
"packages/*",
],

dependenciesMeta

This field lists some extra information related to the dependencies listed in the dependencies and devDependencies fields. 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 (except if noted otherwise, the dependenciesMeta field will be ignored if found within a workspace).

"dependenciesMeta": {
"fsevents": {

built

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 executed (allow-list), and those with built explicitly set to false will simply see their build script warnings downgraded into simple notices.

"built": false,

optional

If true, the build isn't required to succeed for the install to be considered a success, and the dependency may be skipped if its os / cpu / libc fields don't match the current system architecture. It's what the optionalDependencies field compiles down to.

This settings will be applied even when found within a nested manifest, but the highest requirement in the dependency tree will prevail.

"optional": false,

unplugged

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).

"unplugged": true,
},
},

peerDependenciesMeta

This field lists some extra information related to the dependencies listed in the peerDependencies field.

"peerDependenciesMeta": {
"react-dom": {

optional

If true, the selected peer dependency will be marked as optional by the package manager and the consumer omitting it won't be reported as an error.

"optional": true,
},
},

resolutions

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.

"resolutions": {
"relay-compiler": "3.0.0",
"webpack/memory-fs": "0.4.1",
"@babel/core/json5": "2.1.0",
"@babel/core/@babel/generator": "7.3.4",
"@babel/core@npm:7.0.0/@babel/generator": "7.3.4",
},

preferUnplugged

This field instructs Yarn to either force-extract its content on the disk (useful when you need to ship executable binaries for a reason or another) or to force it to stay within its archive (useful when you want your package to contain ALL the sources, including shellscripts, but they aren't useful for runtime purposes).

"preferUnplugged": false,

files

The optional files field is an array of file patterns that describes the entries to be included when your package is installed as a dependency. 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.

Some special files and directories are also included or excluded regardless of whether they exist in the files array.

You can also provide a .npmignore file in the root of your package or in subdirectories, which will keep files from being included. The .npmignore file works just like a .gitignore. If there is a .gitignore file, and .npmignore is missing, .gitignore’s contents will be used instead. The files field overrides .npmignore and .gitignore.

"files": [
"dist/**/*",
"lib/**/*",
],

publishConfig

This field contains various settings that are only taken into consideration when a package is generated from your local sources (either through yarn pack or one of the publish commands like yarn npm publish).

"publishConfig": {

access

Defines the package access level to use when publishing packages to the npm registry. Valid values are public and restricted, but restricted usually requires to register for a paid plan (this is up to the registry you use).

"access": "public",

bin

If present, the top-level bin field from the manifest will be set to this new value before the package is packed to be shipped to remote registries. This won't modify the real manifest, just the one stored within the tarball.

"bin": "./build/bin.js",

browser

Same principle as the publishConfig.bin property; this value will be used instead of the top-level browser field when generating the workspace tarball.

"browser": "./build/browser.js",

executableFiles

By default, for portability reasons, no files except those listed in the bin field will be marked as executable in the resulting package archive. The executableFiles field lets you declare additional fields that must have the executable flag (+x) set even if they aren't directly accessible through the bin field.

"executableFiles": [
"./dist/shim.js",
],

main

Same principle as the `publishConfig.bin` property; this value will be used instead of the top-level `main` field when generating the workspace tarball.
"main": "./build/index.js",

module

Same principle as the `publishConfig.bin` property; this value will be used instead of the top-level `module` field when generating the workspace tarball.
"module": "./build/index.mjs",

registry

If present, will replace whatever registry is defined in the configuration when the package is about to be pushed to a remote location.

"registry": "https://npm.pkg.github.com",
},

installConfig

This field contains various settings that alter how the workspace is installed.

"installConfig": {

hoistingLimits

Defines the highest point where packages can be hoisted, overriding for the current workspace the value initially set for nmHoistingLimits. Valid values are workspaces, dependencies and none

"hoistingLimits": "none",

selfReferences

Defines whether workspaces are allowed to require themselves - results in creation of self-referencing symlinks, overriding for the current workspace the value initially set for nmSelfReferences

"selfReferences": true,
},