package.json

必要項目

The two most important fields in your package.json are name and version, without them your package won’t be able to install. The name and version fields are used together to create a unique id.

name

{
  "name": "my-awesome-package"
}

This is the name of your package. It gets used in URLs, as an argument on the command line, and as the directory name inside node_modules.

yarn add [name]
node_modules/[name]


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

Rules

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

Tips

  • Don’t use the same name as a core Node.js module
  • Don’t put js or node in the name.
  • Keep names short and descriptive. You want people to understand what it is from the name, but it will also be used in require() calls.
  • Make sure that there isn’t something in the registry with the same name.

version

{
  "version": "1.0.0"
}

The current version of your package.

Info

description

{
  "description": "My short description of my awesome package"
}

The description is just a string that helps people understand the purpose of the package. It can be used when searching for packages in a package manager as well.

keywords

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

Keywords are an array of strings that are useful when 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"
}

All packages should specify a license so that users know how they are permitted to use it and any restrictions that you are placing on it.

You are encouraged to use an Open Source (OSI-approved) license unless you have a specific reason not to. If you built your package as part of your job it’s likely best to check with your company before deciding on a license.

Must be one of the following:

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

Various links to documentation, places to file issues and where your package code actually lives.

homepage

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

Homepage 是套件的官網或是文件頁面。

bugs

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

問題反應系统的 URL,或是 email 地址之類的連結。使用者可通過這些方式像您反應問題。

repository

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

Repository 是程式碼托管的位置。

Maintainers

專案的維護者

author

{
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "url": "http://your-website.com"
  },
  "author": "Your Name <you@example.com> (http://your-website.com)"
}

套件作者訊息。一個作者是一個人。

contributors

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (http://other-website.com)"
  ]
}

貢獻者資訊,可能會是多人。

文件類訊息

你可以指定包含在專案中的文件,以及專案的主要入口。

files

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

These are files that are included in your project. You can specify single files, whole directories or use wildcards to include files that meet a certain criteria.

main

{
  "main": "filename.js"
}

專案的入口文件。

bin

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

隨著專案一起被安裝的可執行檔。

man

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

和專案相關的檔案頁面(man page)。

directories

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

當您的套件安裝時,您可以指定確定的位置來放binary files、man page、文件、範例檔等。

Tasks

你的套件可以包含一些可執行腳本或是其他設置訊息。

scripts

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

腳本是定義自動化任務的好方法,例如一些簡單的建制過程或是開發工具。 在 "scripts" 中定義的腳本,可以通過 yarn run <script> 命令來執行。 例如,上述 build-project 腳本可以通過 yarn run build-project 使用,並執行 node build-project.js

一些特殊的腳本名稱。 如果定義了 preinstall 腳本,它會在套件安裝前被使用。 出於相容性考量,installpostinstallprepublish 腳本會在套件完成安裝後被調用。

start 腳本的默認值為 node server.js

config

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

設置你的腳本選項或是參數

相依關係

你的套件很可能相依於其他套件。你可以在你的 package.json 文件裡指定那些相依套件。

dependencies

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

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

You can specify an exact version, a minimum version (e.g., >=) or a range of versions (e.g. >= ... <).

devDependencies

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

These are packages that are only required when developing your package but will not be installed in production.

peerDependencies

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

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

optionalDependencies

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

Optional dependencies can be used with your package, but are not required. If the optional package is not found, installation still continues.

bundledDependencies

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

Bundled dependencies are an array of package names that will be bundled together when publishing your package.

flat

{
  "flat": true
}

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

Note that if your package.json contains "flat": true and other packages depend on yours (e.g. you are building a library rather than an application), those other packages will also need "flat": true in their package.json or be installed with yarn install --flat on the command line.

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"
  }
}

Allows you to override a version of a particular nested dependency. See the Selective Versions Resolutions RFC for the full spec.

Note that installing dependencies via [yarn install --flat] will automatically add a resolutions block to your package.json file.

System

你可以提供和你的套件關聯的系统级的訊息,比如操作系统兼容性之類。

engines

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

Engines 指定使用你的套件客户必須使用的版本,這將檢查 process.versions 以及目前 yarn 版本。

This check follows normal semver rules with one exception. It allows prerelease versions to match semvers that do not explicitly specify a prerelease. For example, 1.4.0-rc.0 matches >=1.3.0, while it would not match a typical semver check.

os

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

此選項指定你的套件的操作系统相容性,它會檢查 process.platform

cpu

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

使用這個選項指定你的套件將只能在某些 CPU 系統架構上運行,這會檢查 process.arch

Publishing

private

{
  "private": true
}

如果你不想你的套件發布到套件管理器,設置為 true

publishConfig

{
  "publishConfig": {
    ...
  }
}

這些配置值將在你的套件發布時使用。比如,你可以给套件附上標籤。