Yarn configuration and the package.json file

Last update on May 28 2020 13:54:16 (UTC/GMT +8 hours)

Configuring your package

Every yarn package must have a package.json file which yarn looks for in order to identify the package. This file configures the behavior of yarn while it is running inside that package.

Let us consider a project named scam-register, this package will have a package.json file located at scam-register/package.json:

{
  "name": "scam-register",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint"
  },
  "dependencies": {
    "core-js": "^3.6.4",
    "vue": "^2.6.11",
    "vue-router": "^3.1.6"
  },
  "devDependencies": {
    "@vue/cli-plugin-babel": "^4.2.0",
    "@vue/cli-plugin-eslint": "^4.2.0",
    "@vue/cli-service": "^4.2.0",
    "babel-eslint": "^10.0.3",
    "eslint": "^6.7.2",
    "eslint-plugin-vue": "^6.1.2",
    "vue-template-compiler": "^2.6.11"
  },
  "eslintConfig": {
    "root": true,
    "env": {
      "node": true
    },
    "extends": [
      "plugin:vue/essential",
      "eslint:recommended"
    ],
    "parserOptions": {
      "parser": "babel-eslint"
    },
    "rules": {}
  },
  "browserslist": [
    "> 1%",
    "last 2 versions"
  ]
}

Use yarn.lock to pin your dependencies

Yarn uses a yarn.lock file in the root of your project to make your dependency resolution fast and reliable. You do not need to touch this file, it is owned by yarn and yarn will change it when managing dependencies.

If you need to make sure that your app works consistently, you will need to always save the yarn.lock file in your code repository.

The package.json file

A. Essentials

The name and version fields are the two most important fields in your package.json file, without them your package can't be installed. Both field are used together to create a unique ID.

name

The name field represents the name of your package, it is used in URLs, as a command line argument as well as the directory name inside node_modules folder.

yarn add [name]

node_module/[name]

https://registry.npmjs.org/[name]/-/[name]-[version].tgz

Rules

Has to be less than or equal to 214 characters (including the @scope/ for scoped packages).
Cannot start with a dot (.) or an underscore (_).
Cannot have an uppercase letter in the name.
Has to use only URL-safe characters.

Tips

Ensure you do not use the same name as a core Node.js module
Make sure that you put js or node in the name.
Keep the names short and descriptive. People have to understand what it is from the name, however, the package will also be used in require() calls.
Ensure that there isn't something in the registry with the same name.

version

This field contains the current version of the package.

{
  "version": "1.0.0"
}

B. Info

description

{
  "description": "Information that describes the package"
}

The description field contains a string that helps people understand the purpose of the package. You can also use it when you are searching for packages in a package manager.

keywords

{
  "keywords": ["short", "relevant", "keywords", "for", "searching"]
}

The keyword field is an array of strings that are useful when you are searching for packages in a package manager.

license

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}

Every package has to specify a license. This enables users know how they are permitted to use the package; it also lets the users know the restrictions that are placed on the package.

Unless you have a specific reason not to, you are encouraged to use an Open Source license. If the package is built as part of your job, it is advisable that you check with your company before you decide on a license.

A license should be one of the following:

A valid SPDX license identifier in the case where you are using a standard license.
A valid SPDX license expression syntax 2.0 expression in the case where you are using multiple standard licenses.
A SEE LICENSE IN <filename> string that points to a <filename> in the top level of your package in the case where you are using a non-standard license.
A UNLICENSED string in the case where you do not want to grant others the right to use a private or unpublished package under any terms.

C. Links

This provides various links to documentation, places where you can file issues and where your package code actually lives.

homepage

{
  "homepage": "https://your-package.org"
}

The homepage specifies the URL to the landing page or the documentation for your package.

bugs

{
  "bugs": "https://github.com/user/repo/issues"
}

This is the URL to your project's issue tracker. It can also be something like an email address. It helps users to find a way to send issues with your package.

repository

{
  "repository": { "type": "git", "url": "https://github.com/user/reponame.git" },
  "repository": "github:user/repo",
  "repository": "gitlab:user/repo",
  "repository": "bitbucket:user/repo",
  "repository": "gist:a1b2c3d4e5f"
}

This specifies the location where the actual codes for your project can be found.

D. Maintainers

This field contains the maintainers of your project.

author

{
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "http://your-website.com"
  },
  "author": "Your Name <[email protected]> (http://your-website.com)"
}

This is the package author's information; an author is usually one person.

contributors

{
  "contributors": [
    { "name": "first Friend", "email": "[email protected]", "url": "http://firstfriends-website.com" }
    { "name": "second Friend", "email": "[email protected]", "url": "http://second-website.com" }
  ],
  "contributors": [
    "First Friend <[email protected]> (http://firstfriends-website.com)",
    "Second Friend <[email protected]> (http://second-website.com)"
  ]
}

This is a list of those that have contributed to your package. The contributors field is an array of people.

E. Files

The files field specify the files that will be included in your project, it includes the main entry point for your project.

files

{
  "files": ["filename.js", "directory/", "glob/*.{js,json}"]
}

These are files that will be included in your project. You could choose to specify single files, whole directories or just use wildcards to include files that meet a certain criterion.

main

{
  "main": "filename.js"
}

The main field is the primary entry point for the functionality for your project.

bin

{
  "bin": "bin.js",
  "bin": {
    "command-name": "bin/command-name.js",
    "other-command": "bin/other-command"
  }
}

These are executable files that are included with your project that will be installed.

man

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}

If you have man pages that are associated with your project, you should add them here.

directories

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}

Whenever you are installing your package, you can specify the exact locations you want to put the binary files, man pages, documentation, examples, etc.

F. Tasks

You could have a package that can include runnable scripts or other configuration.

scripts

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}

Scripts are a great way to automate tasks related to your package, a simple build processes or development tools are some examples. The start script value will default to node server.js.

The start script value will default to node server.js

config

{
  "config": {
    "port": "8080"
  }
}

This is the configuration options or parameters that are used in your scripts.

G. Dependencies

Your package will most likely depend on other packages. Those dependencies can be specified in your package.json file.

dependencies

{
  "dependencies": {
    "package-1": "^3.1.4"
  }
}

These dependencies are the ones that are required in both development and production for your package.

devDependencies

{
  "devDependencies": {
    "package-2": "&0.4.2"
  }
}

These are packages that you only require when developing your package but are not installed in production.

peerDependencies

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}

Peer dependencies enable you to state compatibility of your package with versions of other packages.

optionalDependencies

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}

You can use optional dependencies with your package, but they are not required. If the optional packages are not found, installation will not be aborted.

bundledDependencies

{
  "bundledDependencies": ["package-4"]
}

The bundled dependencies are an array of package names that are bundled together when publishing your package.

flat

{
  "flat": true
}

If your package only permits one version of a given dependency, and you want to enforce the same behavior as yarn install --flat on the command line, you should set this to true.

resolutions

{
  "resolutions": {
    "transitive-package-1": "0.0.29",
    "transitive-package-2": "file:./local-forks/transitive-package-2",
    "dependencies-package-1/transitive-package-3": "^2.1.1"
  }
}

This enables you to override a version of a particular nested dependency.

It should be noted that, installation of dependencies via yarn install -flat automatically adds a resolutions block to your package.json file.

H. System

This field enables you to provide system-level information associated with your package, like the operating system compatibility, etc.

engines

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}

The engines will specify versions of clients that must be used with your package. This will check against process.versions as well as the current version of yarn.

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

This field specifies operating system compatibility for your package. It will check against process.platform.

cpu

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

You should use this to specify your package will only run on certain CPU architectures. The cpu field will perform checks against process.arch.

Publishing

private

{
  "private": true
}

If you don't want your package published in a package manager, you should set this field to true.

publishConfig

{
  "publishConfig": {
    ...
  }
}

These configuration values are the ones that will be used when publishing your package.

Previous: Yarn why and yarn workspaces CLI commands
Next: Yarn envvars and .yarnrc files